Table of Contents
{php}IPAM
Compatible with DokuWiki
Detritus, Elenor Of Tsort, Frusterick Manners, Greebo
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
orboth
) - a list (when the format parameter is either
list
orboth
) 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
orformat=both
) - a box for list of elements (
format=list
orformat=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 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…
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
- 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)