Petals ESB on Ubuntu 24.04 on Azure User Guide

Overview

Petals ESB is an open source enterprise service bus from the OW2 community, built on the Java Business Integration (JBI, JSR-208) standard. It runs a container in which pluggable JBI components - binding components that speak protocols such as SOAP over HTTP, and service engines that transform and route messages - are wired together by an internal message bus (the NMR), so services are connected and mediated without point-to-point coupling. This cloudimg image runs a single Petals node as one Java service on Eclipse Temurin 17, and ships a working end-to-end sample so a real request routes through the bus the moment it boots: the sample Clock service engine is deployed and exposed as a SOAP web service by the SOAP binding component, so a request sent to that endpoint travels through the binding component, across the internal bus to the service engine, and back with a real response. Petals ESB is open source under the GNU Lesser General Public License (LGPL) 2.1. Backed by 24/7 cloudimg support.

What is included:

• Petals ESB 5.4.0 (the petals-esb-default-zip distribution from Maven Central, checksum-pinned) on Eclipse Temurin 17 (LTS)
• A petals-esb.service systemd unit running the Petals container as a dedicated petals system user
• A pre-deployed sample: the Clock service engine (petals-sample-clock) exposed over HTTP/SOAP by petals-bc-soap at 127.0.0.1:8084, so a real message routes through the bus on first boot
• The petals-cli JMX admin command-line tool at /opt/petals-cli
• Two per-VM secrets generated on first boot (the topology passphrase and the JMX admin password) - no shared default identity, and the upstream default petals/petals is never run
• Secure by default: the SOAP endpoint is bound to loopback, and a host firewall (ufw) allows only SSH inbound - the JMX and inter-container transport ports are closed to the network
• 24/7 cloudimg support

This is a headless integration product. There is no web console - Petals is operated over the JMX admin CLI on the VM, and services are reached over loopback or an SSH tunnel. (The optional Petals Cockpit web console is a separate, heavier component and is not part of this single-node appliance.)

Prerequisites

An active Azure subscription, an SSH key pair, and a VNet + subnet in the target region. Standard_B2s (2 vCPU / 4 GiB RAM) is a good starting point - a single Petals node is one JVM with a 1 GiB heap. NSG inbound: allow 22/tcp from your management network only. No inbound application ports are needed - the bus is reached in-process, over loopback, or over an SSH tunnel.

Step 1 - Deploy from the Azure Marketplace

Sign in to the Azure Portal, choose Create a resource, search the Marketplace for Petals ESB by cloudimg, and select Create. On Basics pick your subscription, resource group, region and size; under Administrator account choose SSH public key and paste your key; under Inbound port rules allow SSH (22) only. Then Review + create -> Create.

Step 2 - Deploy from the Azure CLI

az vm create \
  --resource-group <your-rg> \
  --name petals-esb \
  --image <marketplace-image-urn> \
  --size Standard_B2s \
  --admin-username azureuser \
  --ssh-key-values ~/.ssh/id_ed25519.pub \
  --vnet-name <your-vnet> --subnet <your-subnet> \
  --public-ip-sku Standard

Step 3 - Connect to your VM

ssh azureuser@<vm-public-ip>

On first boot petals-firstboot.service rotates the two shipped default secrets to unique per-VM values and then starts petals-esb.service, which recovers the pre-deployed sample. Give it a minute on a fresh VM.

Step 4 - Confirm the node is installed and healthy

. /etc/petals/petals.env
"${JAVA_HOME}/bin/java" -version
cat /opt/petals/system-extensions/petals-esb-container.version
systemctl is-active petals-esb.service
printf 'GET /petals/services/ : HTTP %s\n' "$(curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:8084/petals/services/)"

You should see OpenJDK 17, the Petals container version 5.4.0, an active service, and the SOAP component answering with 200:

openjdk version "17.0.20" 2026-07-21
17.0.20+8 ...
5.4.0
active
GET /petals/services/ : HTTP 200

Step 5 - Route a real message through the bus

The image deploys a working sample: the Clock service engine, exposed as a SOAP web service by the SOAP binding component. Send a time request to the endpoint and the message routes over HTTP into the binding component, across the internal bus to the Clock service engine, and back with the current time - a genuine end-to-end trip through the ESB:

curl -s -X POST http://127.0.0.1:8084/petals/services/ClockHttpEndpoint \
  -H 'Content-Type: text/xml;charset=UTF-8' -H 'SOAPAction: ""' \
  --data '<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:pet="http://petals.ow2.org"><soapenv:Body><pet:time/></soapenv:Body></soapenv:Envelope>'

<?xml version="1.0" encoding="UTF-8"?><soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"><soapenv:Body><timeResponse xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"><timeReturn xsi:type="xsd:string">08/13/2026 08:30:13</timeReturn></timeResponse></soapenv:Body></soapenv:Envelope>

The <timeReturn> value in the response was produced by the Clock service engine and carried back across the bus - proof the container is routing messages. A convenience wrapper is bundled: /opt/petals/bin/clock-roundtrip.sh prints CLOCK_ROUNDTRIP_OK time=... on success.

Step 6 - Retrieve your per-VM secrets

The image ships no shared credential. On first boot both upstream defaults (the topology passphrase and the JMX admin password, each petals out of the box) are rotated to unique per-VM secrets and written to a root-only file:

sudo cat /stage/scripts/petals-credentials.log

The file contains PETALS_JMX_USER (petals), PETALS_JMX_PASSWORD and PETALS_TOPOLOGY_PASSPHRASE, each unique to this VM. In the step below, <PETALS_JMX_PASSWORD> stands for the JMX password value from this file.

Step 7 - Operate the container with the Petals CLI

petals-cli connects to the running container over JMX (loopback, port 7700) and administers it - list and manage components and service assemblies, read the topology, print the container version. Authenticate with the per-VM JMX password:

sudo /opt/petals-cli/bin/petals-cli.sh \
  -h 127.0.0.1 -n 7700 -u petals -p '<PETALS_JMX_PASSWORD>' \
  -c -- version

Petals ESB µKernel 4.4.0
Petals Standalone Shared Memory 4.4.0
Petals ESB Autoloader 1.3.0
OpenJDK Runtime Environment 17.0.20+8 Eclipse Adoptium
Linux 6.17.0-1022-azure amd64

The default password petals is rejected - only your per-VM secret authenticates. Run petals-cli.sh -C for an interactive console; help lists the commands (show, stop, list, monitoring, topology, and more).

Step 8 - The secure-by-default posture

The SOAP endpoint is bound to loopback, both shipped default secrets are rotated per VM, and the host firewall keeps every Petals port off the network. Confirm the SOAP endpoint answers on localhost but is refused on the VM's network NIC, that the credentials file is root-only, and that ufw allows only SSH:

IP=$(hostname -I | awk '{print $1}')
stat -c 'file: %n  perms: %a  owner: %U:%G' /stage/scripts/petals-credentials.log
echo -n "localhost :8084 = HTTP "; curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8084/petals/services/
echo -n "NIC $IP :8084   = "; curl -s -o /dev/null -w '%{http_code}\n' --max-time 4 http://$IP:8084/petals/services/ || echo 'connection refused'
sudo ufw status verbose | grep -E 'Status:|Default:|22/tcp'

file: /stage/scripts/petals-credentials.log  perms: 600  owner: root:root
localhost :8084 = HTTP 200
NIC 10.0.0.18 :8084   = connection refused
Status: active
Default: deny (incoming), allow (outgoing), disabled (routed)
22/tcp                     ALLOW IN    Anywhere                   # SSH

The SOAP endpoint is reachable only on loopback; the JMX (7700) and inter-container transport (7800) ports bind all interfaces by Petals design but are closed to the network by the default-deny firewall. To reach the SOAP endpoint from your workstation, open an SSH tunnel: ssh -L 8084:127.0.0.1:8084 azureuser@<vm-public-ip>.

Step 9 - Deploy your own components and service assemblies

Petals installs JBI artifacts by dropping them into the container's autoloader directory. Copy a component or service-assembly zip into the install directory as the petals user and the container installs and starts it automatically:

sudo install -o petals -g petals -m 0644 my-service-assembly.zip \
  /opt/petals/data/install/
sudo journalctl -u petals-esb -f    # watch it deploy

Petals ships a rich component catalogue on Maven Central (org.ow2.petals) - SOAP, REST, JMS, file transfer, mail and database binding components, plus the Flowable BPMN service engine and more - so you can wire external protocols to internal services. Build service units against the Petals CDK, package them into a service assembly, and deploy as above. The pre-installed Clock + SOAP sample is a minimal, working reference for the consume-endpoint pattern.

Maintenance

• Configuration: the container settings live in /opt/petals/conf/server.properties (topology passphrase, autoloader, transport tuning) and /opt/petals/conf/topology.xml (JMX port and admin credentials); JVM options are in /opt/petals/conf/env.sh (-Xmx1024m stock). Edit, then sudo systemctl restart petals-esb.
• Heap: the default 1 GiB heap suits Standard_B2s; raise -Xmx in /opt/petals/conf/env.sh on larger VMs for heavier integration workloads.
• Service control: sudo systemctl status petals-esb and journalctl -u petals-esb for logs; the container's own log is /opt/petals/logs/petals.log.
• Secrets: the per-VM topology passphrase and JMX admin password are in /stage/scripts/petals-credentials.log (root-only). To reach JMX from another host, tunnel over SSH - never expose port 7700 to the network.
• Firewall: ufw allows only SSH inbound by default; open additional ports deliberately (for example a SOAP endpoint you intend to publish behind TLS) if you expose services.
• Security patches: unattended-upgrades remains enabled so the OS continues to receive security updates automatically.

Support

cloudimg provides 24/7 expert support for this image. Contact support@cloudimg.co.uk.

Petals ESB is open source under the GNU Lesser General Public License (LGPL) 2.1, developed by the OW2 community and Linagora. This image is provided by cloudimg and is not affiliated with or endorsed by the Petals project, OW2 or Linagora.