Newer
Older
[PACKAGE]: ../../raw/master/mkp/curl-0.2.1-20231021.mkp "curl-0.2.1-20231021.mkp"
[EXECUTABLE]: ../../raw/master/mkp/curl_executable-20220410.v7.82.0.mkp "curl_executable-20220410.v7.82.0.mkp"
With this agent plugin you can monitor URLs from the perspective of the monitored host and not the monitoring server ;-)
It is build around cURL from [https://curl.se/](https://curl.se/) based on a idea of Christian Wirtz (doc[at]snowheaven[dot]de) and Ingo Hambrock.
cURL supports a lot of different protocols like:
- dict
- file
- ftp/ftps
- gopher/gophers
- http/https
- imap/imaps
- ldap/ldaps
- rtsp
- scp
- sftp
- smb/smbs
- smtp/smtps
- telnet
- tftp
*Note*: The Plugin is intended to be used with the bakery of the CMK enterprise edition.\
*Note*: At the end of this README you will find a list of cURL options implemented so far.
- [Download the cURL execurable mkp][EXECUTABLE] for Linux and Windows executable in version 7.82.0 and the cURL cert bundle (this package is optional see below).
**Note**: before you update to a newer version, always check the [CHANGELOG](CHANGELOG). There migth be incompatible changes.
**Note**: this plugin needs at leat `curl` version 7.70.0 from April 29 2020 to work.
To check if your system provided `curl` will work you can test it on the cli like this:
- Linux `$ curl https://thl-cmk.hopto.org -q -s -o /dev/null -w %{json}`
- Windows `C:\>curl https://thl-cmk.hopto.org -q -s -o NUL -w %{json}`
{"content_type":"text/html; charset=iso-8859-1","errormsg":null,"exitcode":0,"filename_effective":"/dev/null","ftp_entry_path":null,"http_code":302,"http_connect":0,"http_version":"1.1","local_ip":"1.2.3.4","local_port":38896,"method":"GET","num_connects":1,"num_headers":12,"num_redirects":0,"proxy_ssl_verify_result":0,"redirect_url":"https://thl-cmk.hopto.org/gitlab/","referer":null,"remote_ip":"93.226.242.235","remote_port":443,"response_code":302,"scheme":"HTTPS","size_download":217,"size_header":840,"size_request":81,"size_upload":0,"speed_download":3406,"speed_upload":0,"ssl_verify_result":0,"time_appconnect":0.055328,"time_connect":0.015092,"time_namelookup":0.001096,"time_pretransfer":0.055454,"time_redirect":0.000000,"time_starttransfer":0.063656,"time_total":0.063706,"url":"https://thl-cmk.hopto.org","url_effective":"https://thl-cmk.hopto.org/","urlnum":0,"curl_version":"libcurl/7.81.0 OpenSSL/1.1.1l zlib/1.2.11 libssh2/1.10.0 nghttp2/1.46.0"}
```
If you got something like this `curl: unknown --write-out variable: 'json'`, you need to update your curl executable or use the above package.
---
### Update
*Note*: to update from a pre 20220410 version (if you have used the curl_executable plugin) you need to
- remove the cURL executable rules from WATO
- remove the curl_executable package
- install the new curl_executable package
- update the curl package
- reconfigure your cURL WATO rules (select the executable version to use)
- redeploy the package
---
#### Want to contribute?
Nice ;-) Have a look at the [contribution guidelines](CONTRIBUTING.md "Contributing")
---
<details><summary>Sample output</summary>
<details><summary>Check summary</summary>
![check summary](/doc/sample.png?raw=true "sample output")
</details>
<details><summary>Check details</summary>
![check details](/doc/sample-details.png?raw=true "sample output details")
</details>
</details>
<details><summary>WATO options</summary>
<details><summary>WATO cURL service</summary>
![WATO cURL service](doc/wato.png "WATO cURL service")
</details>
<details><summary>WATO bakery cURL</summary>
![WATO bakery cURL](doc/wato-bakery.png "WATO bakery")
</details>
</details>
To use this plugin with the RAW edition of CMK you need to copy the plugin files from the directory `~/local/share/check_mk/agents/plugins` of your CMK site to the client systems.
<details><summary>Details</summary>
|Windows| script | `curl.ps1` | `C:\ProgramData\checkmk\agent\plugins\curl.ps1` |
|| config | `curl.cfg` | `C:\ProgramData\checkmk\agent\config\curl.cfg` |
|| executable | `curl.exe.32` or `curl.exe.64` | `C:\ProgramData\checkmk\agent\bin\curl.exe` |
|| cert bundle | `curl-ca-bundle.crt` | `C:\ProgramData\checkmk\agent\plugins\curl-ca-bundle.crt` |
|Linux| script | `curl.sh` | `/usr/lib/check_mk_agent/plugins/curl.sh` |
|| config | `curl.cfg` | `/etc/check_mk/curl.cfg` |
|| executable | `curl-i386` or `curl-amd64` | `/usr/lib/check_mk_agent/bin/curl` |
Don't forget to make the Linux script executable (`chmod a+x curl.sh`).
*Note*: the executables and cert bundle are optional. If you don't want to use them, the plugin tryes to use the system provided crul (see: [curl shipped by Microsoft](https://curl.se/windows/microsoft.html)).
<details><summary>Additional files created by the bakery</summary>
The bakrey will dynamicly create some additional files in the _curl_ sub directory under the check_mk agent config directory (Linux: `/etc/check_mk/curl`, Windows: `C:\ProgramData\checkmk\agent\config\curl`). **curl_item_#** equals to the second option of each line in the `curl.cfg` configuration file.
| File | Created by bakery option | Content |
| ---- | ---- | ---- |
| curl_item_#.options | cURL options configured by the bakery | Options line by line |
| curl_item_#.ca_cert | Configure certificate verification -> Certificate to verify against | Cert(chain) as PEM |
| curl_item_#.header | Set request header / Set API key header | Header: Value line by line |
| curl_item_#.post_binary | Send HTTP POST data | Post data as binary |
| curl_item_#.priv_key | Configure authentication -> Private/public key -> Private key | Private key for SCP/SFTP/SCP |
| curl_item_#.regex | Regular expression to expect in content | Regex pattern to match on response |
| curl_item_#.search_header | Strings to expect in header | Strings to search for in header line by line |
| curl_item_#.search_response | Strings to expect in response | Strings to search for in response line by line |
In addition to the options in `curl_item_#.options` from the bakery rules the plugin uses the hard coded options `-q -w %{json} -s -verbose --stderr $TEMP_DIR\curl_session`. If no expected strings are configured, the option `-o NUL` will be added on Windows and `-o /dev/null` on Linux.
---
#### Configuration file
If you are not using the CheckMK agent bakery, than you need to create the config file for the plugin your self.
On each line you have the three fields _service_name_, _curl_item__# and _regex_options_. Thes fields are sepereated by `|`. There are no comments or empty lines allowed.
forum.checkmk.com|curl_item_1|no_regex|
thl-cmk.hopto.org|curl_item_2|case_multiline|
checkmk.com|curl_item_3|nocase_nomultiline|
| cURL option | Bakery Option (Comment) |
|-----| ------ |
| --anyauth | Configure authentication -> Username/Password -> Authentication method -> Any authentication |
| --basic | Configure authentication -> Username/Password -> Authentication method -> Basic authentication |
| --cacert | Configure verification of remote host -> Certificate to verify against |
| --cert-status | Configure verification of remote host -> Use OCSP to check certificate status |
| --compressed-ssh | Set FTP/SCP/SFTP options -> Enable ssh compression |
| --connect-timeout | Set connection limits -> Maximum time to connect |
| --crlf | Advanced settings -> Convert LF to CRLF in upload |
| --digest | Configure authentication -> Username/Password -> Authentication method -> Digest authentication |
| --disable-eprt | Set FTP/SCP/SFTP options -> Passive/Actrive mode FTP active mode -> Don't send EPRT command |
| --disable-epsv | Set FTP/SCP/SFTP options -> Passive/Actrive mode -> FTP passove mode -> Don't send EPSV command |
| --dns-interface | Set DNS options -> Source interface |
| --dns-ipv4-addr | Set DNS options -> IPv4 source address |
| --dns-ipv6-addr | Set DNS options -> IPv6 source address |
| --dns-servers | Set DNS options -> DNS servers |
| --dump-header | Strings to expect in header (Configured as `--dump-header /var/tmp/curl_header` or `--dump-header c:/windows/temp/curl_header`) |
| --ftp-account | Set FTP/SCP/SFTP options -> Account data string |
| --ftp-alternative-to-user | Set FTP/SCP/SFTP options -> String to replace USER command |
| --ftp-create-dirs | Set FTP/SCP/SFTP options -> Create remote dir(s) |
| --ftp-method | Set FTP/SCP/SFTP optionss -> Change working directory method |
| --ftp-pasv | Set FTP/SCP/SFTP options -> Passive/Actrive mode -> FTP passove mode |
| --ftp-pret | Set FTP/SCP/SFTP options -> -> FTP passove mode -> Send PRET before PASV |
| --ftp-skip-pasv-ip | Set FTP/SCP/SFTP options -> Passive/Actrive mode - Use remote IP form control channel for data chanel |
| --ftp-port | Set FTP/SCP/SFTP options -> Passive/Actrive mode -> FTP active mode -> Address to use |
| --ftp-ssl-control | Set FTP/SCP/SFTP optionss -> Require SSL/TLS for FTP login |
| --ftp-ssl-ccc | Set FTP/SCP/SFTP options -> Require SSL/TLS for FTP login -> Send CCC after authenticating |
| --ftp-ssl-ccc-mode | Set FTP/SCP/SFTP options -> Require SSL/TLS for FTP login -> Set CCC mode |
| --hostpubmd5 | Configure verification of remote host -> Expected MD5 hash of pub key |
| --hostpubsha256 | Configure verification of remote host -> Expected SHA256 hash of pub key |
| --http1.0 | Use HTTP version -> Use HTTP 1.0 |
| --http1.1 | Use HTTP version -> Use HTTP 1.1 |
| --http2 | Use HTTP version -> Use HTTP/2 |
| --include | Hardcoded in the agent scripts |
| --insecure | Configure verification of remote host -> Don't verify certificates |
| --ipv4 | Set DNS options -> Resolve names -> IPv4 only |
| --ipv6 | Set DNS options -> Resolve names -> IPv6 only |
| --key | Configure authentication -> Private/public key -> Private key |
| --limit-rate | Set connection limits -> Maximum UP-/Download rate |
| --list-only | Set FTP/SCP/SFTP options -> Enable list only |
| --location-trusted | Configure redirects -> Use authentication on redirects |
| --mail-auth | Set SMTP options -> Mail originator address |
| --mail-from | Set SMTP options -> Mail from address |
| --mail-rcpt | Set SMTP options -> Mail to address |
| --mail-rcpt-allowfails | Set SMTP options -> Allow some mail to addresses to fail |
| --max-filesize | Set connection limits -> Maximum file size |
| --max-time | Set connection limits -> Maximum transfer time |
| --negotiate | Configure authentication -> Username/Password -> Authentication method -> HTTP Negotiate (SPNEGO) authentication |
| --no-alpn | Advanced settings -> Disable Application Layer Protocol Negotiation (ALPN) |
| --no-buffer | Advanced settings -> Disable buffering of the output stream |
| --no-keepalive | Advanced settings -> Disable TCP keep alive on the connection |
| --no-npn | Advanced settings -> Disable Next Protocol Negotiation (NPN) |
| --no-sessionid | Advanced settings -> Disable SSL session-ID reusing |
| --noproxy | Configure proxy server -> Don't use any proxy |
| --ntlm | Configure authentication -> Username/Passwordn -> Authentication method -> NTLM authentication |
| --ntlm-wb | Configure authentication -> Username/Password -> Authentication method -> NTLM authentication with winbind |
| --proxy | Configure proxy server -> Use Proxy -> HTTP |
| --pass | Configure authentication -> Private/public key -> Pass phrase |
| --path-as-is | Advanced settings -> Do not squash .. sequences in URL path |
| --proxy-anyauth | Configure proxy server -> Use Proxy -> Proxy authentication -> Authentication method -> Any authentication |
| --proxy-basic | Configure proxy server -> Use Proxy -> Proxy authentication -> Authentication method -> Basic authentication |
| --proxy-digest |Configure proxy server -> Use Proxy -> Proxy authentication -> Authentication method -> Digest authentication |
| --proxy-negotiate | Configure proxy server -> Use Proxy -> Proxy authentication -> Authentication method -> HTTP Negotiate (SPNEGO) authentication |
| --proxy-ntlm | Configure proxy server -> Use Proxy -> Proxy authentication -> Authentication method -> NTLM authentication |
| --proxy-user | Configure proxy server -> Use Proxy -> Proxy authentication -> Proxy username |
| --referer | Set referer |
| --request | Set SMTP options -> REQUEST command |
| --socks4 | Configure proxy server -> Use Proxy -> SOCKS4 |
| --socks4a |Configure proxy server -> Use Proxy -> SOCKS4a |
| --socks5 | Configure proxy server -> Use Proxy -> SOCKS5 |
| --socks5-basic | Configure proxy server -> Use Proxy -> Proxy authentication -> Authentication method -> SOCKS5 basic authentication |
| --socks5-hostname | Configure proxy server -> Use Proxy -> SOCKS5 hostname |
| --speed-limit | Set connection limits -> Minimum speed |
| --speed-time | Set connection limits -> Minimum speed time |
| --ssl-allow-beast | Advanced settings -> Allow SSL beast security flaw to improve interoperability |
| --ssl-no-revoke | Configure verification of remote host -> Disable cert revocation checks (WinSSL |
| --ssl-reqd | Use TLS/SSL version -> Require SSL/TLS |
| --sslv2 | Use TLS/SSL version -> Use SSLv2 |
| --sslv3 | Use TLS/SSL version -> Use SSLv3 |
| --stderr | Hardcoded in the agent scripts to `--stderr /var/tmp/url_session` or `--stderr c:\windows\temp\url_session` |
| --tcp-fastopen | Advanced settings -> Use TCP fast open option |
| --tcp-nodelay | Advanced settings -> Use TCP no delay option |
| --tlsv1 | Use TLS/SSL version -> Use TLS 1.0 or greater |
| --tlsv1.0 | Use TLS/SSL version -> Use TLS 1.0 |
| --tlsv1.1 | Use TLS/SSL version -> Use TLS 1.1 |
| --tlsv1.2 | Use TLS/SSL version -> Use TLS 1.2 |
| --tlsv1.3 | Use TLS/SSL version -> Use TLS 1.3 |
| --upload-file | Set SMTP options -> Message to send Set headers (SMTP) |
| --user | Configure authentication -> Username/Password -> Username |
| --verbose | Hardcoded in the agent scripts |
| --output | Strings to expect in response (By default `--output /dev/null` or `--output NUL`. If expect strings is configured set to `--output /var/tmp/curl_output` or `--output c:/windows/temp/curl_output`)|
| --use-ascii | Set FTP/SCP/SFTP option -> Enable ASCII transfer |
| --write-out | Hardcoded in the agent scripts to `--write-out %{json}` |