From 3803814def7d5f6eda43b226f1500d6beda89751 Mon Sep 17 00:00:00 2001
From: "Hahn Axel (hahn)" <axel.hahn@unibe.ch>
Date: Mon, 28 Oct 2024 17:25:14 +0100
Subject: [PATCH] add doc file for help page

---
 docs/20_Checks/check_gitlab_tokens.md | 82 +++++++++++++++++++++++++++
 1 file changed, 82 insertions(+)
 create mode 100644 docs/20_Checks/check_gitlab_tokens.md

diff --git a/docs/20_Checks/check_gitlab_tokens.md b/docs/20_Checks/check_gitlab_tokens.md
new file mode 100644
index 0000000..e93bbae
--- /dev/null
+++ b/docs/20_Checks/check_gitlab_tokens.md
@@ -0,0 +1,82 @@
+# Check Gitlab tokens
+
+## Introduction
+
+**check_gitlab_tokens** checks all newer tokens of projects and groups if they expire soon. You can set a warning and a critical level in days.
+
+## Requirements
+
+* curl
+* Bash REST API client<br>A set of class like functions with a http. prefix. <br>Docs: <https://os-docs.iml.unibe.ch/bash-rest-api-client/>
+
+Extract or Git pull the Bash REST API client somewhere in your filesystem. eg. /opt/bash-api-client/. With the parameter `-r <FILE>` you point to the file `rest-api-client.sh`. 
+
+## Syntax
+
+```txt
+./check_gitlab_tokens -h
+______________________________________________________________________
+
+CHECK_GITLAB_TOKENS
+v0.1
+
+(c) Institute for Medical Education - University of Bern
+Licence: GNU GPL 3
+
+https://os-docs.iml.unibe.ch/icinga-checks/Checks/check_gitlab_tokens.html
+______________________________________________________________________
+
+Check gitlab tokens and warn if a token expires soon.
+
+This check fetches the gitlbab tokens created in the last 395 days
+from the Gitlab API. It skips
+
+    - personal access tokens of users
+    - revoked tokens
+
+SYNTAX:
+check_gitlab_tokens [-w WARN_LIMIT] [-c CRITICAL_LIMIT]
+
+OPTIONS:
+
+    -h or --help   show this help.
+
+    -w VALUE       warning level  (default: 30)
+    -c VALUE       critical level (default: 10)
+
+    -g FILE        path to GITLAB_CONFIG; default: /etc/icinga2/gitlab.cfg
+    -r FILE        path to REST_CLIENT; default: ./../inc/rest-api-client.sh
+
+    -s DAYS        Number of days for max age of token; default: 395
+
+PARAMETERS:
+
+    None.
+
+EXAMPLE:
+    check_gitlab_tokens -w 28 -c 7
+
+```
+
+### Parameters
+
+Add directories to check.
+Set a directory that is writable for world or prepared to be accessible for the icinga user.
+
+## Configuration
+
+The script needs to connect to the Gitlab API.
+You need to create a token in a admin group to read all tokens of all projects.
+
+Put 2 bash variabbles into `/etc/icinga2/gitlab.cfg`:
+
+```shell
+GITLAB_API='https://gitlab.example.com/api/v4'
+GITLAB_TOKEN='glpat-1234567890'
+```
+
+You can use another filename for this configuration - but then you need the parameter `-g <FILE>`to reference it.
+
+## Example
+
+`check_gitlab_tokens -r /opt/rest-api-client/rest-api-client.sh`
-- 
GitLab