wazuh · gdiazlo · Dec 20, 2024 · Dec 2, 2024 · Dec 2, 2024 · Dec 2, 2024
diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml
@@ -0,0 +1,42 @@
+name: deploy-gh-pages
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+permissions:
+  contents: write
+  pages: write
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-20.04
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.ref }}
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup mdBook
+        uses: jontze/action-mdbook@v3
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          use-mermaid: true
+      - run: mdbook build
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: './book'
+
+  deploy:
+    needs: build
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
diff --git a/docs/.gitignore b/docs/.gitignore
@@ -0,0 +1 @@
+book
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,25 @@
+# Wazuh Agent Technical Documentation
+
+This folder contains the technical documentation for the Wazuh Agent. The documentation is organized into the following guides:
+
+- **Development Guide**: Instructions for building, testing, and packaging the agent.
+- **Reference Manual**: Detailed information on the agent’s architecture, configuration, and usage.
+- **Diagnostic Guide**: Steps to diagnose errors and resolve common issues.
+
+## Requirements
+
+To work with this documentation, you need **mdBook** installed. For installation instructions, refer to the [mdBook documentation](https://rust-lang.github.io/mdBook/).
+
+## Usage
+
+- To build the documentation, run:
+  ```bash
+  ./build.sh
+  ```
+  The output will be generated in the `book` directory.
+
+- To serve the documentation locally for preview, run:
+  ```bash
+  ./server.sh
+  ```
+  The documentation will be available at [http://127.0.0.1:3000](http://127.0.0.1:3000).
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
@@ -0,0 +1,45 @@
+# Summary
+
+- [Introduction](README.md)
+
+# Development Documentation
+
+- [Introduction](dev/README.md)
+- [Setup Environment](dev/setup.md)
+- [Build Packages](dev/build-packages.md)
+- [Build Image](dev/build-image.md)
+- [Build from Sources](dev/build-sources.md)
+- [Run from Sources](dev/run-agent.md)
+- [Run Tests](dev/run-tests.md)
+
+# Reference Manual
+
+- [Introduction](ref/README.md)
+  - [Description](ref/description.md)
+  - [Architecture](ref/architecture.md)
+  - [Compatibility](ref/compatibility.md)
+- [Getting Started](ref/getting-started/README.md)
+  - [Requirements](ref/getting-started/requirements.md)
+  - [Packages](ref/getting-started/packages.md)
+  - [Installation](ref/getting-started/installation.md)
+- [Configuration](ref/configuration.md)
+- [Modules](ref/modules/README.md)
+  - [File Integrity monitoring](ref/modules/fim/README.md)
+    - [Architecture](ref/modules/fim/architecture.md)
+    - [API Reference](ref/modules/fim/api-reference.md)
+  - [Inventory](ref/modules/inventory/README.md)
+    - [Architecture](ref/modules/inventory/architecture.md)
+    - [API Reference](ref/modules/inventory/api-reference.md)
+  - [Logcollector](ref/modules/logcollector/README.md)
+    - [Architecture](ref/modules/logcollector/architecture.md)
+    - [API Reference](ref/modules/logcollector/api-reference.md)
+- [Upgrade](ref/upgrade.md)
+- [Uninstall](ref/uninstall.md)
+- [Back Up and Restore](ref/backup-restore.md)
+- [Security](ref/security.md)
+- [Performance](ref/performance.md)
+- [Glossary](ref/glossary.md)
+
+# Diagnostic Documentation
+
+- [Diagnostic Guide](diag/diagnostic.md)
diff --git a/docs/book.toml b/docs/book.toml
@@ -0,0 +1,6 @@
+[book]
+authors = ["Vikman Fernandez-Castro"]
+language = "en"
+multilingual = false
+src = "."
+title = "Wazuh Agent Documentation"
diff --git a/docs/build.sh b/docs/build.sh
@@ -0,0 +1,3 @@
+#! /bin/sh
+
+mdbook build
diff --git a/docs/dev/README.md b/docs/dev/README.md
diff --git a/docs/dev/build-image.md b/docs/dev/build-image.md
@@ -0,0 +1 @@
+# Build a Container Image
diff --git a/docs/dev/build-packages.md b/docs/dev/build-packages.md
@@ -0,0 +1 @@
+# Build Packages
diff --git a/docs/dev/build-sources.md b/docs/dev/build-sources.md
@@ -0,0 +1,3 @@
+# Build from Sources
+
+## Build Scripts / Makefiles
diff --git a/docs/dev/run-agent.md b/docs/dev/run-agent.md
@@ -0,0 +1 @@
+# Run from Sources
diff --git a/docs/dev/run-tests.md b/docs/dev/run-tests.md
@@ -0,0 +1 @@
+# Run Tests
diff --git a/docs/dev/setup.md b/docs/dev/setup.md
@@ -0,0 +1,4 @@
+# Set up the Development Environment
+
+## Set up the Toolchain
+## Set up Editor / Debugger
diff --git a/docs/diag/diagnostic.md b/docs/diag/diagnostic.md
@@ -0,0 +1,165 @@
+# Diagnostic Guide
+
+1. **Agent version and service status**
+2. **Configuration files**
+3. **Logs**
+4. **System resource usage**
+
+### Agent Version and Status
+
+#### Linux
+
+```
+/usr/share/wazuh-agent/bin/wazuh-agent -v
+```
+```
+systemctl status wazuh-agent
+```
+
+#### macOS
+
+```
+/Library/Application Support/wazuh-agent/bin/wazuh-agent -v
+```
+
+#### Windows
+
+```
+"C:\\Program Files\\wazuh-agent\\wazuh-agent.exe" -v
+```
+```
+Get-Service -Name wazuh-agent
+```
+
+### Configuration Files
+
+#### Linux
+
+To gather the configuration file, locate the following file:
+
+- /etc/wazuh-agent/wazuh-agent.yml
+
+Copy this filee for analysis.
+
+####  macOS
+
+To gather the configuration file, locate the following file:
+
+- /Library/Application Support/wazuh-agent/etc/wazuh-agent.yml
+
+Copy this filee for analysis.
+
+#### Windows
+
+To gather the configuration file, locate the following file:
+
+- C:\\ProgramData\\wazuh-agent\\etc\\wazuh.yml
+
+Copy this filee for analysis.
+
+### Logs
+
+#### Linux
+
+Use `journald` or `systemctl status wazuh-agent` to capture logs related to `wazuh-agent`.
+
+```bash
+journalctl -u wazuh-agent.service
+```
+
+#### macOS
+
+Use the Unified Logging System (ULS) to extract logs related to `wazuh-agent`.
+
+```bash
+log show --predicate 'process == "wazuh-agent"' --info
+```
+
+#### Windows
+
+Use the Event Viewer to search for logs related to `wazuh-agent`.
+
+### System Resources
+
+#### Linux & macOS
+
+Collect system resource usage data to understand the agent's performance impact. Fill in the table below with the relevant data:
+
+| Daemon               | CPU usage | RAM usage | Disk usage | Network usage               |
+|----------------------|-----------|-----------|------------|-----------------------------|
+| (Global)             |           |           |            | (Connections to port 27000) |
+| `wazuh-agent`        |           |           |            |                             |
+
+#### Steps to collect system resource data
+
+1. **CPU and RAM usage:**
+   - Use the `top` or `htop` command to monitor CPU and RAM usage for `wazuh-agent`.
+2. **Disk usage:**
+   - Use the `df -h` command to check the disk usage of the file system where Wazuh is installed.
+   - Use the `du -h` command to check the disk usage of the Wazuh agent installation (usually _/usr/share/wazuh-agent_).
+3. **Network usage:**
+   - Use the `netstat` or `ss` command to monitor connections to ports 1514 and 1515.
+   - Alternatively, use tools like `iftop` or `nload` to measure real-time network usage.
+
+##### Example commands
+
+1. **CPU and RAM usage:**
+   ```bash
+   top -p $(pgrep -d',' wazuh-agent)
+   top -p $(pgrep -d',' wazuh-modulesd)
+   ```
+2. **Disk usage:**
+   ```bash
+   df -h /usr/share/wazuh-agent
+   df -h /var/lib/wazuh-agent
+   ```
+3. **Network usage:**
+   ```bash
+   netstat -an | grep ':1514\|:1515'
+   ```
+
+#### Windows
+
+Collect system resource usage data to understand the agent's performance impact. Fill in the table below with the relevant data:
+
+| Daemon            | CPU usage | RAM usage | Disk usage | Network usage                     |
+|-------------------|-----------|-----------|------------|-----------------------------------|
+| `wazuh-agent.exe` |           |           |            |                                   |
+
+#### Steps to collect system resource data
+
+1. **CPU and RAM usage:**
+   - Use the Task Manager or the `tasklist` command to monitor CPU and RAM usage for `wazuh-agent.exe`.
+2. **Disk usage:**
+   - Use the `dir` command to check the disk usage of the directory where Wazuh is installed.
+   - Alternatively, use the Disk Management tool or the `Get-PSDrive` PowerShell cmdlet.
+3. **Network usage:**
+   - Use the `netstat` command to monitor connections to ports 1514 and 1515.
+   - Alternatively, use tools like Resource Monitor or PowerShell cmdlets such as `Get-NetTCPConnection`.
+
+##### Example commands
+
+1. **CPU and RAM usage:**
+   - Open Task Manager, go to the "Details" tab, and find `wazuh-agent.exe`.
+   - Or use the command prompt:
+     ```cmd
+     tasklist /fi "imagename eq wazuh-agent.exe"
+     ```
+2. **Disk usage:**
+   - Command prompt:
+     ```cmd
+     dir "C:\\Program Files\\wazuh-agent" /s
+     ```
+   - PowerShell:
+     ```powershell
+     Get-PSDrive -PSProvider FileSystem
+     ```
+3. **Network usage:**
+   - Command prompt:
+     ```cmd
+     netstat -an | findstr ":1514" | findstr ":1515"
+     ```
+   - PowerShell:
+     ```powershell
+     Get-NetTCPConnection -LocalPort 1514,1515
+     ```
diff --git a/docs/ref/README.md b/docs/ref/README.md
diff --git a/docs/ref/architecture.md b/docs/ref/architecture.md
@@ -0,0 +1 @@
+# Architecture
diff --git a/docs/ref/backup-restore.md b/docs/ref/backup-restore.md
@@ -0,0 +1 @@
+# Back Up and Restore
diff --git a/docs/ref/compatibility.md b/docs/ref/compatibility.md
@@ -0,0 +1 @@
+# Compatibility
diff --git a/docs/ref/configuration.md b/docs/ref/configuration.md
@@ -0,0 +1 @@
+# Configuration
diff --git a/docs/ref/description.md b/docs/ref/description.md
@@ -0,0 +1 @@
+# Description
diff --git a/docs/ref/getting-started/README.md b/docs/ref/getting-started/README.md
@@ -0,0 +1 @@
+# Getting Started
diff --git a/docs/ref/getting-started/installation.md b/docs/ref/getting-started/installation.md
@@ -0,0 +1 @@
+# Installation
diff --git a/docs/ref/getting-started/packages.md b/docs/ref/getting-started/packages.md
@@ -0,0 +1 @@
+# Packages
diff --git a/docs/ref/getting-started/requirements.md b/docs/ref/getting-started/requirements.md
@@ -0,0 +1 @@
+# Requirements
diff --git a/docs/ref/glossary.md b/docs/ref/glossary.md
@@ -0,0 +1 @@
+# Glossary
diff --git a/docs/ref/modules/README.md b/docs/ref/modules/README.md
@@ -0,0 +1 @@
+# Modules
diff --git a/docs/ref/modules/fim/README.md b/docs/ref/modules/fim/README.md
@@ -0,0 +1 @@
+# File Integrity monitoring
diff --git a/docs/ref/modules/fim/api-reference.md b/docs/ref/modules/fim/api-reference.md
@@ -0,0 +1 @@
+# API Reference
diff --git a/docs/ref/modules/fim/architecture.md b/docs/ref/modules/fim/architecture.md
@@ -0,0 +1 @@
+# Architecture
diff --git a/docs/ref/modules/inventory/README.md b/docs/ref/modules/inventory/README.md
@@ -0,0 +1 @@
+# Inventory
diff --git a/docs/ref/modules/inventory/api-reference.md b/docs/ref/modules/inventory/api-reference.md
@@ -0,0 +1 @@
+# API Reference
diff --git a/docs/ref/modules/inventory/architecture.md b/docs/ref/modules/inventory/architecture.md
@@ -0,0 +1 @@
+# Architecture
diff --git a/docs/ref/modules/logcollector/README.md b/docs/ref/modules/logcollector/README.md
@@ -0,0 +1 @@
+# Logcollector
diff --git a/docs/ref/modules/logcollector/api-reference.md b/docs/ref/modules/logcollector/api-reference.md
@@ -0,0 +1 @@
+# API Reference
diff --git a/docs/ref/modules/logcollector/architecture.md b/docs/ref/modules/logcollector/architecture.md
@@ -0,0 +1 @@
+# Architecture
diff --git a/docs/ref/performance.md b/docs/ref/performance.md
@@ -0,0 +1 @@
+# Performance
diff --git a/docs/ref/security.md b/docs/ref/security.md
@@ -0,0 +1 @@
+# Security
diff --git a/docs/ref/uninstall.md b/docs/ref/uninstall.md
@@ -0,0 +1 @@
+# Uninstall
diff --git a/docs/ref/upgrade.md b/docs/ref/upgrade.md
@@ -0,0 +1 @@
+# Upgrade
diff --git a/docs/server.sh b/docs/server.sh
@@ -0,0 +1,3 @@
+#! /bin/sh
+
+mdbook serve
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		# Build from Sources

		## Build Scripts / Makefiles