m-agent User Docs

website/docs/m-agent/installation.md

@@ -0,0 +1,42 @@
+---
+id: installation
+title: Install m-agent
+sidebar_label: Installation
+---
+
+---
+
+## Pre-Requisites
+1. Linux OS 
+2. systemd
+3. Experiment specific third-party binaries (to be listed in the experiment docs)
+
+## Installation
+To install m-agent in your target machine, you can execute the following commands in the target machine:
+```
+$ curl -fsSL -o get_m-agent.sh https://github.com/raw/litmuschaos/m-agent/master/scripts/install.sh
+$ chmod 700 get_m-agent.sh
+$ ./get_m-agent.sh
+```
+You can specify any particular m-agent version for installation:
+```
+$ ./get_m-agent.sh --version <VERSION>
+```
+By default, `41365` port is utilized by m-agent. You can specify a custom port at which m-agent should listen for client messages:
+```
+$ ./get_m-agent.sh --port <PORT>
+```
+Finally, you can specify if the installation can take place without using sudo, if it is not present:
+```
+$ ./get_m-agent.sh --no-sudo
+```
+
+To confirm whether the installation was successful or not, you can firstly check if the m-agent service is in an `active` state:
+```
+systemctl status m-agent
+```
+
+Then, you can confirm if the m-agent binary is correctly setup and working:
+```
+m-agent -help
+```

website/docs/m-agent/overview.md

@@ -0,0 +1,34 @@
+---
+id: overview
+title: m-agent
+sidebar_label: Overview
+---
+
+---
+
+Machine Agent, a.k.a. m-agent is a lightweight, platform-generic daemon agent that can remotely inject faults into machine scoped resources as part of the LitmusChaos Experiments.
+
+## Why do you need m-agent?
+In the context of machine-scoped chaos experiments for LitmusChaos, despite using various cloud platform specific VM agents for the execution of the chaos, there have been several limitations such as:
+- Inflexible APIs for remote execution of bash commands, which translates to poor chaos orchestration and chaos rollback abilities.
+- Individual experiment codebase for each cloud platform, which is difficult to maintain.
+- Lack of observability of resources in the target machine during the chaos injection.
+- Limited scope for Litmus probes as they can’t be executed within the target machine.
+
+To address these issues, m-agent has been introduced. m-agent provides many advantages over the current approach, such as:
+- Enhanced OS resource state monitoring in the target machine
+- Ability to run Litmus probes natively within the target machine
+- Establishes the basis for injecting application-level chaos in further iterations
+- Introduces error classification for simplifying the process of their mitigation
+
+## How does m-agent work?
+m-agent is essentially a web server which lies within the target machine, where it performs different actions on behalf of the experiment pod, that lies in the execution plane. These actions include, but are not limited to:
+- Check Steady State
+- Inject Chaos
+- Execute Litmus Probe
+- Revert Chaos
+- Check Liveness
+
+The experiment pod and m-agent communicate with each other using the [websocket](https://en.wikipedia.org/wiki/WebSocket) protocol.
+<img src={require("../assets/m-agent-design.png").default} alt="m-agent design summary" />
+

website/docs/m-agent/uninstallation.md

@@ -0,0 +1,14 @@
+---
+id: uninstallation
+title: Uninstall m-agent
+sidebar_label: Uninstallation
+---
+
+---
+
+If you wish to uninstall m-agent, you can execute the following commands in the target machine:
+```
+$ curl -fsSL -o remove_m-agent.sh https://github.com/raw/litmuschaos/m-agent/master/scripts/uninstall.sh
+$ chmod 700 remove_m-agent.sh
+$ ./remove_m-agent.sh
+```

website/docs/m-agent/usage.md

@@ -0,0 +1,35 @@
+---
+id: usage
+title: m-agent Usage
+sidebar_label: Usage
+---
+
+Upon installing m-agent, you can use it to generate a token for your Chaos Experiment. It will require you to specify an expiry duration for your token. Tokens are valid from a minimum duration of 1 minute to a maximum of 30 days. The token can be generated in two modes:
+
+1. Interactive Mode
+2. Non-Interactive Mode
+
+To generate a token in interactive mode, use the -get-token boolean flag, which will prompt you to select the expiry duration for the token:
+```
+m-agent -get-token
+```
+
+The non-interactive mode can be used to generate token with more flexibility in terms of its expiry duration. Use the -token-expiry-duration flag along with the -get-token flag to use this mode. -token-expiry-duration is a string flag which expects the expiry duration of the token to be specified in the form of a numeric value suffixed with a single alphabet out of 'm' or 'M', 'h' or 'H', and 'd' or 'D' denoting minutes, hours, and days respectively.
+
+For minutes, the corresponding value must lie in between 1 and 60, inclusively. For hours, the corresponding value must lie in the range of 1 to 24, inclusively. Lastly, for days, the corresponding value must lie between 1 to 30, inclusively.
+
+As an instance, to create a token with a validity of 30 minutes, one can use the following command:
+```
+m-agent -get-token -token-expiry-duration 30m
+```
+
+Similarly, a token valid for 15 days from the time of creation can be specified as:
+```
+m-agent -get-token -token-expiry-duration 15D
+```
+
+You can also update the port at which m-agent should listen for the client messages:
+```
+sudo m-agent -updated-port <NEW_PORT>
+sudo systemctl restart m-agent
+```

website/sidebars.js

@@ -165,6 +165,16 @@ module.exports = {
       ]
     },
 
+    // m-agent
+    {
+      "m-agent": [
+        'm-agent/overview',
+        'm-agent/installation',
+        'm-agent/usage',
+        'm-agent/uninstallation'
+      ]
+    },
+
     // Integrations
     {
       Integrations: ['integrations/prometheus', 'integrations/grafana']