Virtual machine (VM)

Hardware requirements

The following requirements have to be in place before the Wazuh VM can be imported into a host operating system:

• The host operating system must be 64-bit with x86_64/AMD64 architecture.

• Enable hardware virtualization in the host firmware.

• Install a virtualization platform, such as VirtualBox, on the host system.

The Wazuh VM is configured with these specifications by default:

This default CPU and RAM match the Quickstart recommendation for 26 to 100 Wazuh agents. Its 50 GB disk matches the recommendation for up to 25 agents and 90 days of alerts. For more agents, extend the disk. For up to 25 agents, you can lower it to 4 CPU cores and 8 GB of RAM when you import the VM. You can adjust the hardware configuration based on the number of protected endpoints and indexed alert data.

Import and access the virtual machine

1. Download the wazuh-5.0.0-rc2.ova file. To check the download, save the sha512 file in the same directory and run the following command. The output must be wazuh-5.0.0-rc2.ova: OK.

   $ sha512sum -c wazuh-5.0.0-rc2.ova.sha512
   

2. Import the OVA into your virtualization platform. In VirtualBox, select File > Import Appliance, then select the wazuh-5.0.0-rc2.ova file. If your host can't spare 8 CPU cores and 16 GB of RAM, lower them before you click Finish. The VM also runs with 4 CPU cores and 8 GB of RAM. To import from a terminal instead, run the following command. To lower the VM to 4 CPU cores and 8 GB of RAM, add --vsys 0 --cpus 4 --memory 8192 to it:

   $ VBoxManage import wazuh-5.0.0-rc2.ova
   

3. If you use VirtualBox, change two settings before you start the VM. Other graphics controllers can freeze the VM window, and without the UTC setting, the VM clock can jump by your time zone offset during the first start.

   1. Select the imported VM and click Settings. In VirtualBox 7.1 and later, switch from Basic to Expert mode at the top-left of the settings window.

   2. In Display, select VMSVGA from the Graphics Controller list.

   3. In System > Motherboard, select Hardware Clock in UTC Time.

   To change both settings from a terminal instead, run the following command while the VM is powered off. Replace <VM_NAME> with the VM's name:

   $ VBoxManage modifyvm "<VM_NAME>" --graphicscontroller vmsvga --rtc-use-utc on
   

4. Start the VM. The first start configures the VM and takes 5 to 10 minutes.

5. Log in on the VM console, or over SSH to the VM's IP address. To find the address, run the following command on the console. Use the inet address of the interface on the network you connect from. With the default single network adapter, that is eth0.

   $ ip -4 addr
   

   Use these credentials:

   • User: wazuh-user

   • Password: wazuh

   You must change this password at your first login, because the VM ships with it expired. The SSH root user login is disabled. The wazuh-user has sudo privileges. To switch to root, execute the following command:

   $ sudo -i
   

   The VM runs Amazon Linux in FIPS mode. For SSH key login, use an RSA or ECDSA key. Ed25519 keys are refused.

6. Check that the first start has finished:

   $ sudo systemctl status wazuh-starter
   

   It shows Active: activating (start) while the first start runs. When the first start has finished, it removes its own unit, so the command reports Unit wazuh-starter.service could not be found. You also see this after any later reboot. If it shows failed, the first start stopped with an error, and the Wazuh dashboard doesn't start. To see why, run sudo journalctl -u wazuh-starter. A line such as httpclient-dispatch-4 ERROR null, followed by a java.util.ConcurrentModificationException trace, can follow Done with success in the output. It doesn't mean that the first start failed.

Access the Wazuh dashboard

The admin password is generated for this VM at its first start. To print it, run the following command in the VM:

$ sudo grep '^WAZUH_INDEXER_ADMIN_PASSWORD=' /etc/wazuh-indexer/export/credentials.env | cut -d= -f2-

When the first start has finished, access the Wazuh dashboard in a web browser with these credentials. Replace <VM_IP_ADDRESS> with the VM's IP address from step 5 of Import and access the virtual machine:

• URL: https://<VM_IP_ADDRESS>

• User: admin

• Password: the one the command above prints

The Wazuh indexer and Wazuh dashboard passwords, including this one, are in /etc/wazuh-indexer/export/credentials.env. The Wazuh manager API passwords are in /etc/wazuh-manager/export/credentials.env. In this file, WAZUH_MANAGER_API_PASSWORD is the password of the wazuh user, and WAZUH_MANAGER_WUI_PASSWORD is the password of the wazuh-internal-client user. Only root can read these files. Keep both files, because the Wazuh components read them. To change a password, use /usr/share/wazuh-indexer/tools/wazuh-passwords-tool.sh.

To print the password of the wazuh user, run the following command in the VM:

$ sudo grep '^WAZUH_MANAGER_API_PASSWORD=' /etc/wazuh-manager/export/credentials.env | cut -d= -f2-

Until you trust the VM's certificate authority, your web browser warns about the Wazuh dashboard certificate. To trust it, copy /etc/wazuh-dashboard/export/ca.pem to your computer, then import it into your web browser or operating system as a trusted certificate authority.

The file is readable by root only, so copy it over SSH with sudo. Run the following command on your computer. On Windows, run it in Command Prompt, because PowerShell can change the encoding of the file it writes:

$ ssh wazuh-user@<VM_IP_ADDRESS> sudo cat /etc/wazuh-dashboard/export/ca.pem > wazuh-dashboard-ca.pem

Then import wazuh-dashboard-ca.pem into your web browser or operating system as a trusted certificate authority.

Configuration files

All components in this virtual image are configured to work out of the box. However, all components can be fully customized. These are the configuration file locations:

• Wazuh manager: /etc/wazuh-manager/wazuh-manager.conf

• Wazuh indexer: /etc/wazuh-indexer/opensearch.yml

• Wazuh dashboard: /etc/wazuh-dashboard/opensearch_dashboards.yml

• Wazuh agent: /var/ossec/etc/ossec.conf

Refer to the User manual section to learn more about configuring Wazuh components.

The VM sets the Wazuh indexer heap to a quarter of its RAM at its first start. To change it later, for example, after you change the RAM of the VM, edit the -Xms and -Xmx values in /etc/wazuh-indexer/jvm.options, then restart the Wazuh indexer. Your values are kept after a reboot because the VM sets the heap only at its first start.

Network configuration

By default, the network interface type is set to Bridged Adapter. The VM attempts to obtain an IP address from the network DHCP server. Alternatively, you can give the VM a static IP address as described in Set a static IP address. If the VM's address changes after its first start, reissue its certificates as described in the Reissue the Wazuh manager certificates and Reissue the Wazuh dashboard certificate sections.

Enroll additional Wazuh agents

Once the virtual machine is imported and running, it is ready for monitoring using the preinstalled Wazuh agent. To monitor additional endpoints, enroll Wazuh agents on them with an enrollment token. Wazuh 5.x agents connect to the VM on TCP port 1517 for enrollment and for their connection, while older agents still use the legacy ports.

1. Run the following command in the VM as root to create an enrollment token. Replace <VM_IP_ADDRESS> with the address the agents use to reach the VM. It must be an address in the VM's certificates. At its first start, the VM adds only the addresses of network interfaces that have a default route. On a network without a gateway, such as a VirtualBox host-only network, reissue the certificates first. If the address has changed since then, see Reissue the Wazuh manager certificates below.

   # /var/wazuh-manager/bin/wazuh-manager-authd --create-enrollment-token --address <VM_IP_ADDRESS>
   

   Copy the token, the long string in the output.

2. Deploy the Wazuh agent on each endpoint, and use the token as the value of WAZUH_ENROLLMENT_TOKEN. See the Wazuh agent installation guide for more information.

Reissue the Wazuh manager certificates

Wazuh agents verify the Wazuh manager with its agent listener certificate, /etc/wazuh-manager/certs/remoted.pem. Clients of the Wazuh manager API verify it with /etc/wazuh-manager/certs/apid.pem. The VM issues both certificates at its first start, for its hostname, for the addresses of its network interfaces that have a default route, and for loopback. If the VM's address changes later, or agents reach it through an address that is not on the VM, such as a NAT port forward, agents fail to verify the Wazuh manager. Creating an enrollment token for that address fails with ERROR 9025: Enrollment token refused: address not in certificate SAN.

Reissue both certificates from the VM's own certificate authority. Run the following steps in the VM as root. Agents enrolled before the change keep trusting the Wazuh manager because the certificate authority stays the same.

1. Stop the Wazuh manager, then check that none of its processes are still running:

   # systemctl stop wazuh-manager
   # /var/wazuh-manager/bin/wazuh-manager-control status
   

   If any line ends in is running..., stop them:

   # /var/wazuh-manager/bin/wazuh-manager-control stop
   

2. List the addresses that agents and Wazuh manager API clients use to reach the VM. Set the following lines in /etc/wazuh-manager/local.env, and create the file if it doesn't exist. Each key can appear only once, so if the file already has these keys, replace their values. Replace <NEW_ADDRESS> with the address. Prefix each entry with IP: for an IP address or DNS: for a hostname, and separate several entries with commas:

   WAZUH_MANAGER_REMOTED_CERT_SANS=IP:<NEW_ADDRESS>
   WAZUH_MANAGER_APID_CERT_SANS=IP:<NEW_ADDRESS>
   

   The lists replace the addresses the VM discovers, and loopback is always added. For a NAT port forward, forward TCP port 1517 to the VM and list the address agents use. Then restrict the file to root:

   # chown root:root /etc/wazuh-manager/local.env
   # chmod 600 /etc/wazuh-manager/local.env
   

3. Move both current certificate pairs to a backup directory. A pair left in place keeps the old addresses.

   # mkdir -p /root/wazuh-certs-backup
   # mv /etc/wazuh-manager/certs/remoted.pem /etc/wazuh-manager/certs/remoted-key.pem /etc/wazuh-manager/certs/apid.pem /etc/wazuh-manager/certs/apid-key.pem /root/wazuh-certs-backup/
   

4. Issue the new certificates, then publish the certificate authority bundle to the agents:

   # /var/wazuh-manager/bin/wazuh-manager-resolve-credentials --install
   # /var/wazuh-manager/bin/wazuh-manager-certs stamp
   

   The output includes a line that starts with resolve-credentials: /etc/wazuh-manager/certs/remoted.pem: issued; and lists the new address. If that line is missing, the certificate was not issued. Move the files in /root/wazuh-certs-backup/ back to /etc/wazuh-manager/certs/ and start the Wazuh manager.

5. Start the Wazuh manager:

   # systemctl start wazuh-manager
   

6. Create an enrollment token for the new address to confirm the change. The command now succeeds:

   # /var/wazuh-manager/bin/wazuh-manager-authd --create-enrollment-token --address <NEW_ADDRESS>
   

Afterwards, point the agents enrolled before the change to the new address.

Reissue the Wazuh dashboard certificate

The Wazuh dashboard certificate, /etc/wazuh-dashboard/certs/dashboard.pem, names the VM's host name and the addresses of its network interfaces that have a default route at its first start. After an address change, the Wazuh dashboard keeps working, but the web browser reports a name mismatch for the new address. To reissue the certificate, run the following commands in the VM as root:

# systemctl stop wazuh-dashboard
# rm -f /etc/wazuh-dashboard/certs/dashboard.pem /etc/wazuh-dashboard/certs/dashboard-key.pem
# /usr/share/wazuh-dashboard/bin/resolve-credentials --install
# systemctl start wazuh-dashboard

The new certificate covers the addresses the VM has now. To set the list yourself, add WAZUH_DASHBOARD_CERT_SANS to /etc/wazuh-dashboard/local.env before you run the commands, with an IP: or DNS: prefix on each entry. Restrict the file to root with chmod 600. The Wazuh dashboard keeps its stored passwords.

Troubleshooting