Talk by Eric Lippmann

1. Icinga Camp | Berlin | 7th of March 2017
Icinga Web 2
How to Write Modules

2. Icinga Web 2.4.1
released on Jan 20, 2017

3. • Send commands over the Icinga 2 API
• SSL support for MySQL resources
• Export detail views to JSON and CSV
• Change password for DB users

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

6. How to Write Modules

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

8. • 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?

9. • Lessons learned from Icinga-web 1.x
• Keep framework overhead at a minimum
• Keep it simple
• No XML

10. /bin/rm

11. • Simple
• Reliable
• Performant

12. • Convention over configuration
• Put things in the right place rather than
having to configure where things are
• Reasonable defaults
• INI config files

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

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

15. • 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

16. • Create and activate a new module
• mkdir -p /usr/share/icingaweb2-
modules/showcase
• icingacli module list installed
• icingacli module enable showcase

18. • Module meta information in module.info

19. CLI Commands

20. • 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

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

22. application/clicommands/SayCommand.php

24. icingacli <module> <command> <action>
icingacli showcase say something

25. • Namespaces help to encapsulate modules
• Every modules has its own namespace
built from its name:
IcingaModule<module>
• The namespace for CLI commands is
Clicommands

27. • Document your code
• CLI help is generated from
documentation
• Get help with --help

29. • 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

32. CLI Parameter Handling

33. • Standalone and named parameters
• Default values
• Instance of IcingaCliParams available
in $this->params

38. Bring it to the Web

39. • MVC
• Available actions in controllers
• View scripts for output and presentation
• Library code as “model”

40. • Every action in a controller is automatically
a route in Web 2
icingaweb2/<module>/<controller>/<action>

41. • Let‘s create a controller
application/controllers/GinController.php

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

45. • Create the view script
• One directory per controller
• One view script per action
application/views/scripts/gin/flavors.phtml

47. • Automatic borders
• Scrollable “content”
• Fixed “controls” for header elements

49. Tab Navigation

52. Menu Entries

53. • Users may add their own menu entries
• Modules provide menu entries
• configuration.php in the base directory of
the module

56. Dashboards

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

59. • Hide “controls” in dashboards

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

63. Styles

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

68. Feed the View with Data

69. • Set data in controllers with
$this->view->key = value;
• Use data in views with
$this->key or
$key

72. Translation

73. • 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

74. Configuration

75. • /etc/icingaweb2/modules/<module>/
• $this->Config(<file>)
• Default file is config.ini
• Available in Web and CLI

76. [section]
key = value
$this->Config()->get(‘key’);
$this->Config()->get(‘nokey’, ‘default-value’)

77. Vendor CSS and JS Files

80. www.icinga.org
dev.icinga.org
git.icinga.org
Thank You!
@icinga
/icinga
+icinga