Wazuh

Installing Wazuh Central Components Natively on Ubuntu Server

This guide provides a streamlined procedure for installing the Wazuh indexer, Wazuh server, and Wazuh dashboard on a single Ubuntu node. This native installation avoids the complexities of container networking and volume permissions.

Prerequisites

Step 1: System Preparation

Before starting the installation, ensure the OS is up to date and the identity of the server is established.

1. Set the Hostname

Identify the server clearly on your network (e.g., SecuServer).

sudo hostnamectl set-hostname SecuServer

2. Update System Packages

Ensure all base repositories and installed packages are current.

sudo apt update && sudo apt upgrade -y

3. Reboot

Apply any kernel updates or hostname changes.

sudo reboot

Step 2: The Wazuh Installation

Wazuh provides an installation assistant that automates certificate generation and component linking. We use a version-specific URL to ensure the script downloads correctly.

1. Download and Run the Assistant

The -a flag performs an automated all-in-one installation.

curl -sO https://packages.wazuh.com/4.14/wazuh-install.sh && sudo bash ./wazuh-install.sh -a

2. Wait for Completion

The script will install the Indexer, Server, and Dashboard. This typically takes 5–15 minutes depending on hardware and network speed.

Step 3: Securing Credentials

Once the installation finishes, the terminal will display a Summary block.

CRITICAL: Copy the admin password immediately. It is randomly generated and required for the first login.

If you lose this password, you can retrieve it from the installation files by running:

sudo tar -O -xvf wazuh-install-files.tar wazuh-install-files/wazuh-passwords.txt

Step 4: Accessing the Dashboard

Wazuh natively listens on port 443 and enforces HTTPS.

  1. Open your browser and navigate to: https://<your_server_ip>
  2. Bypass SSL Warning: Since the certificates are self-signed by the script, your browser will show a "Not Secure" warning. Click Advanced and then Proceed.
  3. Login: Use the username admin and the password saved from Step 3.

Troubleshooting Note: Port 80 vs. 443

If the page refuses to connect, ensure you are explicitly typing https:// in the address bar. Wazuh does not listen on standard HTTP (Port 80) and will not automatically redirect you.

Managing Users and Roles in Wazuh (v4.14+)

Wazuh operates on a two-layered security model. Because it is built on top of OpenSearch, user management is split into two parts:

  1. OpenSearch (Indexer): Controls access to the underlying database and system settings.
  2. Wazuh App: Controls access to security agents, rules, and dashboards.

To give a user full administrative privileges, you must grant them permissions in both layers. This guide outlines how to properly create an admin, how to assign restricted roles, and what those roles mean.

Part 1: How to Create a Super Admin User

Creating a Super Admin requires setting up the user in the Indexer, assigning them a specific "Backend role" to bypass system locks, and then mapping them to the Wazuh App.

Step 1: Create the User & Assign the Backend Role (Database Layer)

The all_access system role is locked by default. To make someone an admin, you must assign them the admin Backend Role, which automatically inherits full system access.

  1. Click the Global Menu (≡) in the top left corner.
  2. Navigate to Indexer management -> Security.
  3. Click on Internal users, then click the blue Create internal user button.
  4. Enter a descriptive Username and a secure Password.
  5. Scroll down to the Backend roles section. Type admin into the box and click Add another backend role (or press Enter).
  6. Click the blue Create (or Save) button at the bottom right.

Step 2: Map the User to the Wazuh App (Application Layer)

Now that the user has database access, you must grant them control over the Wazuh security features.

  1. Click the W. logo in the top left to return to the Wazuh App.
  2. Navigate to Server management -> Security.
  3. Click the Roles mapping tab at the top of the screen.
  4. Click the blue Create Role mapping button.
  5. Role mapping name: Give it a recognizable name (e.g., username_admin_access).
  6. Roles: Check the box for administrator.
  7. Scroll down to the Mapping rules section. Under Map internal users, click the dropdown and select the user you created in Step 1.
  8. Crucial: If there is a default "Custom rule" (e.g., one that looks for the word "wazuh"), click the red trash can icon to delete it.
  9. Click Save role mapping.

The user is now a full Super Admin and can log in with total system control.

Part 2: How to Assign Standard Roles (e.g., Read-Only)

If you want to create a restricted user (like a junior analyst who can only view alerts but cannot change settings), the process is nearly identical, but you skip the admin backend role.

  1. Create the User: Go to Indexer management -> Security -> Internal users and create the user. Do not add anything to the "Backend roles" section. Just save the username and password.
  2. Map the Role: Go to Server management -> Security -> Roles mapping and click Create Role mapping.
  3. Select the Restricted Role: In the Roles dropdown, select a restricted role like readonly instead of administrator.
  4. Map the User: Select your new user from the "Map internal users" dropdown, delete any default custom rules, and save.

Understanding Built-In Roles

Wazuh comes with several pre-configured roles that dictate what a user can see and do within the application.

Note: Always ensure that users requiring global server configuration access are granted the admin Backend Role in the Indexer management menu, as Wazuh App roles alone cannot override database-level restrictions.

Installing Wazuh Agent on Linux (Ubuntu/Debian)

Overview

This guide outlines the procedure for installing the Wazuh agent on Debian-based systems. It includes the standard repository method for local LAN devices, as well as a direct package installation method for devices on restricted networks (e.g., forced OpenVPN tunnels) where standard DNS or APT updates fail.

Prerequisites

Method 1: Standard APT Installation (Main Network)

Use this method for standard servers that have unrestricted outbound internet access to resolve and update package lists.

1. Repository Configuration

Import the Wazuh GPG key and add the official repository to your package manager's sources.

curl -s https://packages.wazuh.com/key/GPG-KEY-WAZUH | sudo gpg --no-default-keyring --keyring gnupg-ring:/usr/share/keyrings/wazuh.gpg --import && sudo chmod 644 /usr/share/keyrings/wazuh.gpg

echo "deb [signed-by=/usr/share/keyrings/wazuh.gpg] https://packages.wazuh.com/4.x/apt/ stable main" | sudo tee /etc/apt/sources.list.d/wazuh.list

sudo apt-get update

2. Agent Installation

Install the agent while passing the Manager's FQDN as an environment variable.

sudo WAZUH_MANAGER='wazuh.goonersnas.com' apt-get install wazuh-agent

Method 2: Direct Package Installation (VPN/Restricted Networks)

Use this method if the host is behind a strict VPN that blocks or fails to resolve standard APT update servers. This bypasses the package manager entirely.

1. Download the Package

Fetch the specific .deb installer directly from the Wazuh servers.

wget https://packages.wazuh.com/4.x/apt/pool/main/w/wazuh-agent/wazuh-agent_4.14.5-1_amd64.deb

2. Force Installation via DPKG

Install the downloaded package, passing the local IP address instead of the domain name to bypass local DNS resolution failures.

sudo WAZUH_MANAGER='192.168.0.153' dpkg -i wazuh-agent_4.14.5-1_amd64.deb

Service Activation & Verification

Once the agent is installed, enable it to start on boot and initiate the service.

sudo systemctl daemon-reload
sudo systemctl enable wazuh-agent
sudo systemctl start wazuh-agent

Troubleshooting Common Issues

1. Error: "Job for wazuh-agent.service failed because a timeout was exceeded"

On newer Linux kernels or slower hardware, the systemd default timeout is often too short for the Wazuh initialization process. Extend the timeout with an override file:

sudo mkdir -p /etc/systemd/system/wazuh-agent.service.d/
echo -e "[Service]\nTimeoutStartSec=300" | sudo tee /etc/systemd/system/wazuh-agent.service.d/timeout.conf
sudo systemctl daemon-reload
sudo systemctl restart wazuh-agent

2. Manual Enrollment (If client.keys is empty)

If the agent installs but fails to retrieve a key from the manager, trigger enrollment manually:

sudo /var/ossec/bin/agent-auth -m 192.168.0.153

3. Fix: Agent Stuck in "Pending" or "Never Connected" Status

If the agent shows as registered in the dashboard but is "never connected", or if checking the local state (sudo grep ^status /var/ossec/var/run/wazuh-agentd.state) shows status='pending', the agent cannot resolve or reach the Manager's address. Update the configuration to use the static IP.

Step A: Edit the configuration file

sudo nano /var/ossec/etc/ossec.conf

Step B: Locate the <client> block and update the <address> to the Manager's IP

<client>
  <server>
    <address>192.168.0.153</address>
    <port>1514</port>
    <protocol>tcp</protocol>
  </server>
</client>

Step C: Restart the agent to apply changes

sudo systemctl restart wazuh-agent