From 7755e50f7cce6d5f8ecc701de89c496e36d0b59a Mon Sep 17 00:00:00 2001 From: Vehbi Sinan Tunalioglu Date: Fri, 29 Mar 2024 00:23:26 +0800 Subject: [PATCH 1/2] chore(docs): annotate config.yaml with field descriptions --- config.yaml | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/config.yaml b/config.yaml index 489f004..cadbd81 100644 --- a/config.yaml +++ b/config.yaml @@ -1,6 +1,9 @@ hosts: - - name: somehost + - ## Name of the host (required) + name: somehost + ## External URL for the host (optional) url: https://internal.documentation/hosts/somehost + ## List of tags for the host (optional) tags: - oranges - strawberries From 30077b4e55835602658b7bcdf6e87d7401e08e06 Mon Sep 17 00:00:00 2001 From: Vehbi Sinan Tunalioglu Date: Fri, 29 Mar 2024 00:23:51 +0800 Subject: [PATCH 2/2] docs: update README with some (rudimentary) content --- README.md | 144 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 141 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index ee38753..ab04bbb 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,136 @@ -# Lazy Hacker's Linux Host Patrol +

+
+ logo +
+
Host Patrol
+ Lazy Hacker's Linux Host Patrol +

+
+ GitHub Release + GitHub Issues or Pull Requests + GitHub Issues or Pull Requests +
+

-> **TODO** Provide minimum viable documentation. +Host Patrol (`lhp`) is a command-line application to retrieve +information from remote hosts. The information is retrieved over SSH +by executing small [scripts]. Then, the information is compiled into +JSON to be further analysed or visualised on its [Website]. + +The report contains following information for each host: + +1. **Hardware resources:** (v)CPU count, total RAM, root filesystem disk size +1. **Kernel information** +1. **Linux distribution information** as in [os-release] +1. List of all **Docker containers** (in all states) +1. List of **systemd services** +1. List of **systemd timers** +1. List of **authorised SSH public keys** found on the host +1. **Cloud information:** (if any) + - Cloud provider name + - Host instance identifier + - Host type + - Region + - Availability zone + - Local hostname + - Local address + - Remote hostname + - Remote address + - Reserved address + +## Installation + +> [!NOTE] +> +> A statically compiled executable is planed. See [Issue 32]. + +Currently, the easiest way to install the command-line application is +via Nix: + +```sh +nix profile install --file https://github.com/vst/lhp/archive/v.tar.gz app +``` + +## Usage + +`lhp` assumes that you are able to connect to remote hosts via SSH: + +```sh +ssh my-host +``` + +Indeed, `lhp` uses `ssh` under the hood. Therefore, if you can `ssh`, +you can `lhp`! + +> [!NOTE] +> +> If you are using SSH public key authentication to connect to host +> and your SSH private key is password-protected, use SSH-agent and +> unlock your private key first. + +You can pass hosts via CLI arguments: + +```sh +lhp compile --host my-host-1 --host my-host-2 > /tmp/lhp-report.json +``` + +This command connects to hosts in parallel. If any of the hosts cause +an error, entire operation will fail. To ignore failed hosts, you can +use `--stream` mode: + +```sh +lhp compile --stream --host my-host-1 --host my-host-2 | jq --slurp . > /tmp/lhp-report.json +``` + +Alternatively, you can use a configuration file which has additional +benefit of attaching static information to your hosts such as external +documentation URL and/or tags. The configuration file looks like as +follows: + +```yaml +## config.yaml +hosts: + - ## Name of the host (required) + name: somehost + ## External URL for the host (optional) + url: https://internal.documentation/hosts/somehost + ## List of tags for the host (optional) + tags: + - oranges + - strawberries + - name: otherhost + url: https://internal.documentation/hosts/otherhost + tags: + - apples + - strawberries +``` + +Then, you can use this configuration file instead of specifying hosts +individually on the command-line: + +```sh +lhp compile --config config.yaml > /tmp/lhp-report.json +``` + +..., or: + +```sh +lhp compile --stream --config config.yaml | jq --slurp . > /tmp/lhp-report.json +``` + +Users can process/analyse the JSON output themselves or use [Website] +to list, tabulate and visualise the information. + +> [!NOTE] +> +> The [Website] stores the report locally in the Web browser using +> local storage. It is not sent to any third party service. You can +> study the [Website source-code] that is automatically published to +> GitHub Pages. ## Development -The codebase comes with a Nix shell. You can use `direnv` for conveience: +The codebase comes with a Nix shell. You can use `direnv` for convenience: ```sh direnv allow @@ -31,4 +157,16 @@ For testing and building: dev-test-build ``` +## License + +Copyright © 2024 Vehbi Sinan Tunalioglu. This work is licensed +under [MIT License]. + + +[Issue 32]: https://github.com/vst/lhp/issues/32 +[Website]: https://thenegation.com/lhp +[os-release]: https://www.freedesktop.org/software/systemd/man/latest/os-release.html +[scripts]: ./src/scripts +[Website source-code]: ./website +[MIT License]: https://opensource.org/license/mit