DokuWiki

It's better when it's simple

User Tools

Site Tools


plugin:phpipam

{php}IPAM

Compatible with DokuWiki

  • 2018-04-22 "Greebo" unknown
  • 2017-02-19 "Frusterick Manners" yes
  • 2016-06-26 "Elenor Of Tsort" yes
  • 2015-08-10 "Detritus" yes

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

Last updated on
2018-09-11
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!

Setup

Please, read and follow carefully the following steps.

External requirements

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

Download and Installation

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.

API configuration

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.

Syntax

General

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…

Direct

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

attribute name value type query for list of
sid or nid or just id or num
(or longer forms: subnetid or networkid or number)
integer subnet index hosts
vid or vlanid integer VLAN index subnets
did or deviceid integer Device index hosts
cidr or net (or longer forms subnet or network) or ret CIDR notation subnet address hosts
vlan or vnet or vpc or vdom integer VLAN number subnets
lid or locationid or placeid or siteid integer Location index hosts
loc or location or place or site integer Location index subnets
tid or tagid or statusid integer Tag (address status) index hosts
eid or rackid or cabinetid integer Enclosure rack index devices

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.

Indirect

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

attribute name source object index destination object
s2n or s2s Section SubNets
f2n or f2s master-subnet or Folder (of course virtual) SubNets
v2n or v2s Virtual layer 2 network SubNets
n2n or n2s virtual Network Number! SubNets
l2n or l2s Location SubNets
d2n or d2s Device SubNets
r2n or r2s virtual Routing and forwarding SubNets
t2d device Type Devices
l2d Location Devices
e2d Enclosure rack Devices
l2e Location Enc. racks
d2e Device Enc. racks
22v layer 2 domain Vlan

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

Filtering

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

Customisations

The plugin can be personalized in many ways.

Styling Support

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:

query for main div classes title h6 class main presentation box each presentation field
Subnets phpipam_subnet-XX and phpipam_section-YY subnet_name phpipam_subnets phpipam_subnet_ZZ
VLAN phpipam_vlan-XX vlan_name phpipam_vlans phpipam_vlan_ZZ
Device phpipam_device-XX and phpipam_section-YY device_name phpipam_devices phpipam_device_ZZ
Location phpipam_location-XX location_name phpipam_locations phpipam_location_ZZ
ip Tag phpipam_tag-XX tag_name phpipam_tags phpipam_tag_ZZ
Rack phpipam_rack-XX rack_name

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.

Translation Support

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.

Others

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. :-)

Code evolution

This plugin is opensource.

Bugs, Feature Requests and Patches

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.

Missing Features & To Do

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 no 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 improvment.

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…

Other Questions

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.

Latest Commits

plugin/phpipam.txt · Last modified: 2018-09-15 20:21 by gilcot