1 6456042b 2022-01-06 o package icinga provides a client to the Icinga2 HTTP API.
 2 6456042b 2022-01-06 o 
 3 6456042b 2022-01-06 o [![godocs.io](http://godocs.io/olowe.co/icinga?status.svg)](http://godocs.io/olowe.co/icinga)
 4 6456042b 2022-01-06 o 
 5 6456042b 2022-01-06 o ## Quick Start
 6 6456042b 2022-01-06 o 
 7 6456042b 2022-01-06 o A Client manages interaction with an Icinga2 server.
 8 6456042b 2022-01-06 o It is created using Dial. Provide the address, in `host:port` form, API username and password, and a `http.Client`:
 9 6456042b 2022-01-06 o 
10 6456042b 2022-01-06 o 	client, err := icinga.Dial("icinga.example.com:5665", "icinga", "secret", http.DefaultClient)
11 6456042b 2022-01-06 o 	if err != nil {
12 6456042b 2022-01-06 o 		// handle error
13 6456042b 2022-01-06 o 	}
14 6456042b 2022-01-06 o 
15 2c4d16ae 2021-12-23 o Icinga2 servers in the wild often serve self-signed certificates which
16 2c4d16ae 2021-12-23 o fail verification by Go's tls client. To ignore the errors, Dial the server
17 6456042b 2022-01-06 o with a modified `http.Client`:
18 2c4d16ae 2021-12-23 o 
19 9ab732cd 2021-12-30 o 	t := http.DefaultTransport.(*http.Transport)
20 9ab732cd 2021-12-30 o 	t.TLSClientConfig = &tls.Config{InsecureSkipVerify: true}
21 9ab732cd 2021-12-30 o 	c := http.DefaultClient
22 9ab732cd 2021-12-30 o 	c.Transport = t
23 6456042b 2022-01-06 o 	client, err := icinga.Dial(addr, user, pass, c)
24 2c4d16ae 2021-12-23 o 	if err != nil {
25 2c4d16ae 2021-12-23 o 		// handle error
26 2c4d16ae 2021-12-23 o 	}
27 2c4d16ae 2021-12-23 o 
28 6456042b 2022-01-06 o Methods on `Client` provide API actions like looking up users and creating hosts:
29 2c4d16ae 2021-12-23 o 
30 6456042b 2022-01-06 o 	user, err := client.LookupUser("oliver")
31 6456042b 2022-01-06 o 	if err != nil {
32 6456042b 2022-01-06 o 		// handle error
33 6456042b 2022-01-06 o 	}
34 6456042b 2022-01-06 o 	host := Host{
35 6456042b 2022-01-06 o 		Name: "myserver.example.com",
36 6456042b 2022-01-06 o 		CheckCommand: "hostalive"
37 6456042b 2022-01-06 o 		Address: "192.0.2.1"
38 6456042b 2022-01-06 o 		Address6: "2001:db8::1"
39 6456042b 2022-01-06 o 	}
40 6456042b 2022-01-06 o 	if err := client.CreateHost(host); err != nil {
41 6456042b 2022-01-06 o 		// handle error
42 6456042b 2022-01-06 o 	}
43 6456042b 2022-01-06 o 
44 6456042b 2022-01-06 o Not all functionality of the Icinga2 API is implemented.
45 6456042b 2022-01-06 o For more detail, see the [godocs][godocs].
46 6456042b 2022-01-06 o 
47 6456042b 2022-01-06 o [godocs]: https://godocs.io/olowe.co/icinga
48 6456042b 2022-01-06 o 
49 6456042b 2022-01-06 o ## Why Another Package?
50 6456042b 2022-01-06 o 
51 6456042b 2022-01-06 o The [icinga2 terraform provider][tf] uses the package [github.com/lrsmith/go-icinga2-api/iapi][lrsmith].
52 6456042b 2022-01-06 o As I read the source code I felt I wasn't reading idiomatic Go as detailed in documents like [Effective Go][effectivego].
53 6456042b 2022-01-06 o Other properties of `iapi` felt unusual to me:
54 6456042b 2022-01-06 o 
55 6456042b 2022-01-06 o * The client to the API has the  confusing name `server`.
56 6456042b 2022-01-06 o * Every HTTP request creates a new http.Client.
57 6456042b 2022-01-06 o * Types have superfluous names like `HostStruct` instead of just `Host`.
58 6456042b 2022-01-06 o * Every response body from the API is decoded from JSON into one data strucutre, marshalled into JSON again, then unmarshalled back into another.
59 6456042b 2022-01-06 o * Every error returned from a function has a new name, rather than reusing the idiomatic name `err`.
60 6456042b 2022-01-06 o 
61 6456042b 2022-01-06 o If I was being paid, I'd create a fork and contribute patches upstream to carefully avoid breaking functionality of existing users of `iapi`.
62 6456042b 2022-01-06 o 
63 6456042b 2022-01-06 o But I'm not being paid ;)
64 6456042b 2022-01-06 o 
65 6456042b 2022-01-06 o [effectivego]: https://go.dev/doc/effective_go
66 6456042b 2022-01-06 o [tf]: https://registry.terraform.io/providers/Icinga/icinga2/latest
67 6456042b 2022-01-06 o [lrsmith]: https://godocs.io/github.com/lrsmith/go-icinga2-api/iapi