check_http.md

Check Httpd

Introduction

Makes an http request with a given method. Additionally you can verify the response.

Requirements

• curl - a tool for transferring data from or to a server
• jq - commandline JSON processor - optional: for param -j

Syntax

______________________________________________________________________

CHECK_HTTP
v1.0

(c) Institute for Medical Education - University of Bern
Licence: GNU GPL 3

https://os-docs.iml.unibe.ch/icinga-checks/Checks/check_http.html
______________________________________________________________________

Makes an http request with a given method.
Additionally you can verify the response by
- http status code
- content in http response header
- content in http response body
- content that is NOT in http response body

SYNTAX:
  check_http [-h]
  check_http [-m METHOD] -u URL [-c PARAMS]\
      [-j FILTER] \ 
      [-s STATUSCODE] \
      [-b REGEX] [-n REGEX] [-r REGEX] \
      [-l LABEL]

OPTIONS:

  -h               this help

PARAMETERS:

  Define request:
  -u URL           Set url to fetch; eg. https://www.example.com/
  -m METHOD        Set a method, eg. HEAD; default: GET
  -c PARAMS        additional curl params; curl will be executed 
                   with '[PARAMS] -si -X [METHOD] --connect-timeout 10 [URL]'

  Filtering:
  -j JQ-FILTER     for JSON Response: filter response body by jq

  What to check:
  -s STATUSCODE    exact Statuscode to check; 3 digits; by default critical
                   is a statuscode greater equal 400
  -r REGEX         Regex must match in http response header
  -b REGEX         Regex must match in response body
  -n REGEX         Regex must NOT match in response body

  Output:
  -l LABEL         set a custom label; default: METHOD + URL eg.
                   "GET https://example.com/status (200)"

EXAMPLES:

  check_http -u https://www.example.com/
                   Check if GET request to url responds with 200..3xx status. 

  check_http -m HEAD -u https://www.example.com/
                   Check if HEAD request to url responds with 200..3xx status

  check_http -u [URL] -s 403
                   Check if the GET request to url has a wanted status code.
                   You can verify if a protected url is not accessible.

  check_http -u [URL] -b "contact"
                   Check if the GET request to url responds with 200..3xx 
                   status and the response body contains "contact".

  check_http -u [URL] -n "error occured"
                   Check if the GET request to url responds with 200..3xx 
                   status and the response body NOT contains "error occured".

  check_http -u [URL] -s 200 -b -b "contact" -n "error occured"
                   Combine code, a matching search and a non matching one.

Examples

Simple check of an url

check_http -u https://www.example.com/ is a check that makes an http GET request. The queck is OK if the responded status code is no error - if it is 2xx (OK) or a redirect (3xx).

OK: GET https://www.example.com/ (200)

Command: curl -si -X GET https://www.example.com/

Found:
- Http status is a 2xx OK [200]

Http HEAD of an url

You can set the method with -m. ./check_http -m head -u https://www.example.com/ responds

OK: HEAD https://www.example.com/ (200)

Command: curl -si -X HEAD https://www.example.com/

Found:
- Http status is a 2xx OK [200]

Exact status code

With -m you can verify if the status code matches exactly a given value. You also can set a code for http error to ensure if a protected url really is blocking the request.

Maybe you don't deny the access like

• ./check_http -u https://www.example.com/memberarea -s 403
• ./check_http -u https://www.example.com/config/settings.json -s 403

Or you can check a flag file that must be absent.

• ./check_http -u https://www.example.com/flag_maintenance.txt -s 404

Matching content

You can verify if the response matches a given regex. You can search in the response header with -r REGEX and in the response body with -b REGEX.

check_http -u [URL] -b "contact" will resppns OK if the status code is not an error (lower 400) and the word "contact" is found in response body.

JSON filtering

With the parameter -j JQ-FILTER the jq command will be applied on the response body. Whenever you add -j a search in the body with params -b REGEX and -n REGEX won't be applied to the complete response body but on the result after filtering with jq. So you can build API checks that respond a json structure.

Keycloak responds on its health url

$ curl -k https://keycloak.example.com:8443/health 
{
    "status": "UP",
    "checks": [
    ]
}

First test a filter string on command line

curl -k https://keycloak.example.com:8443/health | jq ".status"

Its result is just "UP" - all other json stuff is blown away. This filter we put into the -j param:

./check_http -u "https://keycloak.example.com:8443/health" -j ".status" -b "UP" returns

OK: GET https://keycloak.example.com:8443/health (200)

Found:
- jq filter [.status] matches
- Http status is a 2xx OK [200]
- [UP] was found in body

Hints:
Content after jq filter: "UP"