Icinga Camp | Berlin | 7th of March 2017

Icinga Web 2How to Write Modules

Icinga Web 2.4.1released on Jan 20, 2017

• Send commands over the Icinga 2 API

• SSL support for MySQL resources• Export detail views to JSON and

CSV• Change password for DB users

• Monitoring action bar• Announce banner• SELinux policy• Forked Zend Framework 1

How to Write Modules

• Should I? Why?• Open Source• Great community

• It’s straight forward• Icinga Web 2 is stable, future-proof

and easy to understand• No deep knowledge of PHP, HTML,

CSS and JS required• So, why not?

• Lessons learned from Icinga-web 1.x

• Keep framework overhead at a minimum

• Keep it simple• No XML

/bin/rm

• Simple• Reliable• Performant

• Convention over configuration• Put things in the right place rather

than having to configure where things are

• Reasonable defaults• INI config files

• Zend Framework 1.x• jQuery version 1 and 2• HTMLPurifier, JShrink, Parsedown,

dompdf, lessphp

• Where to start?• Install Icinga Web 2• Extend the module path

• Give the module a name• Keep it simple• Reflect what it does• Module name used in PHP

Namespaces, URLs and paths in the file system

• Create and activate a new module• mkdir -p /usr/share/icingaweb2-

modules/showcase • icingacli module list installed• icingacli module enable showcase

• Module meta information in module.info

CLI Commands

• Icinga CLI is designed to offer all application logic of Web 2 and its modules also in the CLI

• Helps to provide cronjobs, plugins, tools and even small services

• Bash autocompletion

• Just create a file with the name of the command in application/clicommands

application/clicommands/SayCommand.php

icingacli <module> <command> <action>

icingacli showcase say something

• Namespaces help to encapsulate modules

• Every modules has its own namespace built from its name: Icinga\Module\<module>

• The namespace for CLI commands is Clicommands

• Document your code• CLI help is generated from

documentation• Get help with --help

• Successful actions return exit code 0• Erroneous actions print readable

error messages because all exceptions in CLI are caught

• In this case the exit code is always 1• Get full stacktrace with --trace

CLI Parameter Handling

• Standalone and named parameters• Default values• Instance of Icinga\Cli\Params

available in $this->params

Bring it to the Web

• MVC• Available actions in controllers• View scripts for output and

presentation• Library code as “model”

• Every action in a controller is automatically a route in Web 2

icingaweb2/<module>/<controller>/<action>

• Let‘s create a controller

application/controllers/GinController.php

https://…/icingaweb2/showcase/gin/flavors

• Create the view script• One directory per controller• One view script per action

application/views/scripts/gin/flavors.phtml

• Automatic borders• Scrollable “content”• Fixed “controls” for header

elements

Tab Navigation

Menu Entries

• Users may add their own menu entries

• Modules provide menu entries• configuration.php in the base

directory of the module

Dashboards

• Create own dashboard• Or extend existing ones• configuration.php

• Hide “controls” in dashboards

• Enable autorefresh with one single function call in the action that should auto refresh

Styles

• public/css/module.less• LESS extends CSS• Just use CSS if you want• Module styles are isolated

Feed the View with Data

• Set data in controllers with$this->view->key = value;

• Use data in views with$this->key or$key

Translation

• PHP: $this->translate(‘Translate Me’);• icingacli module enable translation• icingacli translation refresh module

shwocase de_DE• Use Poedit• icingacli translation compile module

showcase de_DE

Configuration

• /etc/icingaweb2/modules/<module>/

• $this->Config(<file>)• Default file is config.ini• Available in Web and CLI

[section]key = value

$this->Config()->get(‘key’);

$this->Config()->get(‘nokey’, ‘default-value’)

Vendor CSS and JS Files

www.icinga.orgdev.icinga.orggit.icinga.org

Thank You!@icinga/icinga+icinga