Skip to main content

· 5 min read

Introduction to Proxmox Webhook Notifications

Proxmox VE 8.3 introduces an exciting new feature to its notification system—webhook notifications. This enables users to trigger HTTP requests for events such as system updates, cluster node issues, or backup job statuses. With support for customizable headers and body content, this feature seamlessly integrates with webhook-compatible services, enhancing your automation workflows.

In this guide, we'll walk you through the Webhook notification setup process, highlighting key configuration details such as `content-type' and escaping request bodies.

Why Use Webhooks?

Webhooks provide a powerful way to automate notifications and integrate Proxmox with external services. For example:

  • Notify your team on Slack or Discord about backup completion.
  • Trigger an external monitoring tool like Prometheus Alertmanager or Uptime Kuma.
  • Automate workflows in services like Zapier or IFTTT.

Setting Up Webhook Notifications in Proxmox VE 8.3

Step 1: Access the Notification Settings

  1. Log in to your Proxmox web interface.
  2. Navigate to DatacenterNotificationsNotification Targets.

Step 2: Add a New Webhook Target

  1. Click Add and select Webhook as the target type.

  2. Fill in the following fields:

    • Endpoint Name: Provide a name for the webhook (e.g., proxmobo).
    • Method/URL: Enter the HTTP method (POST) and the webhook URL (e.g., http://192.168.0.1:8123).
    • Headers: Add any required headers. For example:
      • Content-Type: application/json
    • Body: Define the request body. Here’s an example:
      {
      "title": "{{ escape title }}",
      "message": "{{ escape message }}"
      }
  3. Click OK to save the target.

Why Escaping is Important

Escaping is essential to ensure that special characters, such as line breaks (\n), quotation marks, and other control characters in the notification content, do not break the webhook payload format.

Step 3: Enable the Webhook in the Notification Matcher

The Notification Matcher determines which notifications are sent to your configured targets. You must enable the webhook here.

  1. Navigate to Datacenter → Notifications → Notification Matchers.
  2. Select the default-matcher or create a new matcher.
  3. Edit the matcher: • Go to the Targets to Notify tab. • Select your webhook target (e.g., proxmobo) along with any other desired targets.
  4. Click OK to save.

Step 4: Test the Webhook

  1. Select the newly created webhook target.
  2. Click Test to send a test notification.
  3. Verify the webhook payload in your endpoint logs.

ProxMobo’s Native Push Notification Support

As of our latest ProxMobo update, you can now receive notifications directly to your mobile device without relying solely on webhooks. This native push notification feature complements the webhook setup described above, providing a streamlined way to stay informed about critical events from anywhere.

Getting Started with Native Push Notifications in ProxMobo

  1. Update ProxMobo: Ensure you’re running the latest version of ProxMobo, which includes push notification support (requires Proxmox VE >= 8.3).

  2. Enable Notifications in the App: Open the ProxMobo app and navigate to navigation toolbar (ellipsis) → Notification. Turn on push notifications to authorize ProxMobo to send alerts to your device. ProxMobo will help you configure webhook and notification matcher settings in Proxmox VE.

  3. Receive Alerts Instantly:

Once configured, ProxMobo will send real-time push alerts to your phone or tablet, allowing you to quickly act on important events even if you’re not actively monitoring Proxmox’s interface.

Why Consider Native Push Notifications?

• Simplicity: No need to manage additional endpoints or integrate with third-party services. • Instantaneous Updates: Receive alerts right on your device’s home screen. • Complementary to Webhooks: Use push notifications for quick status checks, and rely on webhooks for more complex automation workflows.

By incorporating native push notifications, you enrich your notification strategy. Whether you prefer the granular control of webhooks or the convenience of direct mobile alerts, ProxMobo and Proxmox VE >= 8.3 give you the flexibility to build the notification system best suited to your needs.

Tips & Tricks

Set Notification Mode to “Notification System”

When performing backups, Proxmox’s default Notification Mode is set to Auto. If you encounter issues where webhook notifications are not triggered, try setting the Notification Mode to Notification System. This ensures that the webhook-based notification system is explicitly used.

Here’s how to adjust it during a backup job:

  1. Go to the Backup menu for a specific container or virtual machine.
  2. In the Notification Mode dropdown, select Notification System.

This adjustment helps ensure notifications are routed correctly, especially if you’re testing webhook functionality.

Content-Type Header

The Content-Type header is crucial for proper webhook payload processing. Here are a few examples:

For Text-Based Payloads:

Content-Type: text/plain

Body example:

title: Backup Complete
message: The scheduled backup completed successfully.

For JSON Payloads:

Content-Type: application/json

Body example:

{
"title": "Backup Complete",
"message": "The scheduled backup completed successfully."
}

Common Use Cases • Alerting: Route backup failure notifications to a monitoring system. • Task Automation: Use webhooks to start other services or tasks after specific events. • Third-Party Integration: Easily connect Proxmox notifications with tools like Slack, Discord, or custom dashboards.

Conclusion

The new webhook notification target in Proxmox VE 8.3 opens up endless possibilities for integrating your infrastructure with external systems. Whether you’re notifying a team, triggering workflows, or logging events, the flexibility of this feature makes automation simple and powerful.

· 2 min read

Why Use the QEMU Guest Agent?

The QEMU Guest Agent allows better communication between the host and guest VM, enabling features like retrieving the VM's IP address, which is particularly useful when using tools like ProxMobo for remote management.

Setting Up QEMU Guest Agent on Linux VMs

Step 1: Enable QEMU Guest Agent in Proxmox

  1. In the Proxmox web interface, select your VM.
  2. Go to "Hardware" > "Add" > "QEMU Guest Agent".
  3. Start the VM if it's not already running.

Step 2: Install QEMU Guest Agent in the VM

For Ubuntu/Debian:

apt update
apt install qemu-guest-agent

For Redhat based systems:

yum install qemu-guest-agent

Step 3: Enable and Start the QEMU Guest Agent Service

systemctl enable qemu-guest-agent
systemctl start qemu-guest-agent

Step 4: Verify Installation

To verify that the QEMU Guest Agent is running:

systemctl status qemu-guest-agent

You should see output indicating that the service is active and running.

Retrieving IP Address in ProxMobo

Once the QEMU Guest Agent is set up, you can see your VM's IP address in ProxMobo. For detailed instructions on viewing IP addresses and troubleshooting, please refer to our IP Address Retrieval documentation.

Troubleshooting

If you don't see the IP address in ProxMobo:

  1. Ensure the QEMU Guest Agent is running in the VM.
  2. Restart the VM if necessary.
  3. Check that the VM's network configuration is correct.

By following these steps, you'll be able to easily retrieve your Linux VM's IP address in ProxMobo, streamlining your VM management process.

· 2 min read

Why Use a Serial Console?

Using a serial console, as documented for Proxmox VE (a qemu/kvm virtualization tool), allows direct connection to your running VMs. It's an efficient alternative to VNC, providing solutions for capturing detailed messages during system failures which might be impossible on a VNC screen.

Here’s a practical example:

qm status 101
# Output: status: running
qm terminal 101
# Output: starting serial terminal on interface serial0 (press control-O to exit)

Setting Up Serial Console Access in Fedora

Configuration on the Host Node

  1. Add a Virtual Serial Port to the VM: For VM ID 101, open the node's Shell.
  2. Edit VM Configuration:
    • Open /etc/pve/qemu-server/101.conf, add serial0: socket at the end of the file.
    • Alternatively, use qm set 101 -serial0 socket.
  3. Reboot the VM: Ensure the serial port option in the VM's hardware settings is correctly saved.

Unsaved Serial Port Setting

Unsaved Serial Port Setting

Saved Serial Port Setting

Saved Serial Port Setting

Configuring GRUB and Linux Boot Parameters in the Fedora VM/Guest

In your Fedora VM, open terminal:

  1. Backup GRUB Configuration first:
    cp -nv /etc/default/grub /etc/default/grub.bak
  2. Edit GRUB Configuration:
    • Open /etc/default/grub using vi /etc/default/grub.
    • Find the GRUB_TERMINAL_OUTPUT line and modify it to GRUB_TERMINAL_OUTPUT="console serial".
    • Find the GRUB_CMDLINE_LINUX line and update it to GRUB_CMDLINE_LINUX="quiet console=tty1 console=ttyS0,115200"
  3. Update GRUB:
    grub2-mkconfig --output=/boot/grub2/grub.cfg

Once all done, reboot the VM.

Validate Serial Port

After completing the above steps, it's crucial to validate that the serial port is functioning correctly:

  1. Go to the node's Shell, try qm terminal 101 (assuming VM Id is 101). You should get output starting serial terminal on interface serial0
  2. Go to the VM's Console tab, on the top right toolbar, click on the Console dropdown, and ensure that the xterm.js option is enabled as below
Validate Serial Port via xtermjs

Connecting to the VM via ProxMobo Terminal

ProxMobo simplifies the process of connecting to your VM via a serial console in your phone. Here's how you can do it:

  1. Open ProxMobo: Navigate to your VM.
  2. Access Serial Console: Open the Terminal either from the ... menu, or from the CONSOLE section at the bottom of the VM view
Connecting to the VM via ProxMobo Terminal

· 3 min read

Why Use a Serial Console?

Using a serial console, as documented for Proxmox VE (a qemu/kvm virtualization tool), allows direct connection to your running VMs. It's an efficient alternative to VNC, providing solutions for capturing detailed messages during system failures which might be impossible on a VNC screen.

Here’s a practical example:

qm status 101
# Output: status: running
qm terminal 101
# Output: starting serial terminal on interface serial0 (press control-O to exit)

Setting Up Serial Console Access in Ubuntu 20+

Configuration on the Host Node

  1. Add a Virtual Serial Port to the VM: For VM ID 101, open the node's Shell.
  2. Edit VM Configuration:
    • Open /etc/pve/qemu-server/101.conf, add serial0: socket at the end of the file.
    • Alternatively, use qm set 101 -serial0 socket.
  3. Reboot the VM: Ensure the serial port option in the VM's hardware settings is correctly saved.

Unsaved Serial Port Setting

Unsaved Serial Port Setting

Saved Serial Port Setting

Saved Serial Port Setting

Configuring GRUB and Linux Boot Parameters in the Ubuntu VM/Guest

In your Ubuntu VM, open terminal:

  1. Backup GRUB Configuration first:
    sudo cp -nv /etc/default/grub /etc/default/grub.bak
  2. Edit GRUB Configuration:
    • Open /etc/default/grub using sudo vi /etc/default/grub.
    • Find the GRUB_TERMINAL line and modify it to GRUB_TERMINAL="console serial".
    • Find the GRUB_CMDLINE_LINUX_DEFAULT line and update it to GRUB_CMDLINE_LINUX_DEFAULT="console=tty1 console=ttyS0,115200"
  3. Update GRUB:
    sudo update-grub

Once all done, reboot the VM.

Validate Serial Port

After completing the above steps, it's crucial to validate that the serial port is functioning correctly:

  1. Go to the node's Shell, try qm terminal 101 (assuming VM Id is 101). You should get output starting serial terminal on interface serial0
  2. Go to the VM's Console tab, on the top right toolbar, click on the Console dropdown, and ensure that the xterm.js option is enabled as below
Validate Serial Port via xtermjs

Connecting to the VM via ProxMobo Terminal

ProxMobo simplifies the process of connecting to your VM via a serial console in your phone. Here's how you can do it:

  1. Open ProxMobo: Navigate to your VM.
  2. Access Serial Console: Open the Terminal either from the ... menu, or from the CONSOLE section at the bottom of the VM view
Connecting to the VM via ProxMobo Terminal