Apache Karaf on Ubuntu 24.04 on Azure User Guide

Overview

Apache Karaf is a modern, polymorphic OSGi-based application and runtime container from the Apache Software Foundation (Apache-2.0). It provides hot deployment, dynamic configuration, a rich provisioning system and a powerful SSH management console for running modular Java applications and microservices. The cloudimg image ships Karaf 4.4.11 as a single systemd service on OpenJDK 17, configured so the stock karaf/karaf default login is never shipped: a unique console credential is generated on the VM's first boot, so no two deployments share a password and nothing is baked into the image.

What is included:

• Apache Karaf 4.4.11 (pinned, SHA-256 verified binary distribution, Apache-2.0) at /opt/karaf
• OpenJDK 17 (openjdk-17-jdk-headless) as the Java runtime
• Karaf SSH management console on TCP 8101
• Per-VM karaf console credential rotated at first boot into etc/users.properties
• Default karaf/karaf credential removed; wrong-credential logins rejected
• apache-karaf.service running as an unprivileged karaf user
• Hardened, fully patched Ubuntu 24.04 LTS base
• 24/7 cloudimg support

Prerequisites

• An Azure VM launched from this cloudimg image (recommended size Standard_B2s or larger)
• A network security group (NSG) allowing inbound TCP 22 (SSH) and TCP 8101 (Karaf console) from only the admin networks that need them
• SSH access as azureuser
• sshpass or an SSH client on your workstation to reach the Karaf console

Restrict TCP 8101 in your NSG to your administrative subnets. Do not expose the Karaf console to the whole internet.

Step 1: Verify Karaf is running

SSH in as azureuser, then confirm the service is active and the console is listening on 8101 (Karaf takes ~30-60s to fully start on first boot):

sudo systemctl status apache-karaf.service --no-pager -n 0
sudo ss -tln | grep 8101

Expected output:

● apache-karaf.service - Apache Karaf OSGi runtime (cloudimg)
     Loaded: loaded (/etc/systemd/system/apache-karaf.service; enabled; preset: enabled)
     Active: active (running) since Sun 2026-07-19 08:05:15 UTC; 1min 20s ago
       Docs: https://www.cloudimg.co.uk/guides/apache-karaf-on-ubuntu-24-04-azure/
   Main PID: 2155 (karaf)
      Tasks: 76 (limit: 4661)
     Memory: 266.6M (peak: 270.3M)
LISTEN 0      50                      *:8101             *:*

Step 2: Read the per-VM console credential

The karaf username and its randomly generated password are written to a root-only credentials file at first boot:

sudo cat /root/karaf-credentials.txt

Expected output (your password will differ — it is unique to this VM):

# apache-karaf — Per-VM Credentials
# Apache Karaf OSGi runtime — administer over the SSH console on port 8101.
# From your workstation (open port 8101 in your Azure NSG first):
#   ssh -p 8101 karaf@<your-vm-ip>
# then run e.g.  feature:list   system:version   bundle:list
#
KARAF_SSH_USER=karaf
KARAF_SSH_PASSWORD=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
KARAF_SSH_HOST=<your-vm-ip>
KARAF_SSH_PORT=8101

Step 3: Connect to the Karaf console

Use the generated credential to log in to the Karaf SSH console and confirm the runtime version. From the VM itself:

PASS=$(sudo grep '^KARAF_SSH_PASSWORD=' /root/karaf-credentials.txt | cut -d= -f2-)
sshpass -p "$PASS" ssh -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null \
  -o PreferredAuthentications=password -o PubkeyAuthentication=no \
  -p 8101 karaf@127.0.0.1 'system:version'

Expected output:

4.4.11

From a remote workstation, replace 127.0.0.1 with the VM's IP (open TCP 8101 in your NSG first), or use the bundled client: /opt/karaf/bin/client -a 8101 -h <vm-ip> -u karaf.

Step 4: List installed features and bundles

The Karaf console exposes the full provisioning and bundle model. List the installed features and running bundles:

PASS=$(sudo grep '^KARAF_SSH_PASSWORD=' /root/karaf-credentials.txt | cut -d= -f2-)
sshpass -p "$PASS" ssh -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null \
  -o PreferredAuthentications=password -o PubkeyAuthentication=no \
  -p 8101 karaf@127.0.0.1 'feature:list -i'

Expected output (installed features):

Name         | Version | Required | State   | Repository      | Description
-------------+---------+----------+---------+-----------------+------------------------------------
feature      | 4.4.11  | x        | Started | standard-4.4.11 | Features Support
shell        | 4.4.11  | x        | Started | standard-4.4.11 | Karaf Shell
deployer     | 4.4.11  | x        | Started | standard-4.4.11 | Karaf Deployer
bundle       | 4.4.11  | x        | Started | standard-4.4.11 | Provide Bundle support
config       | 4.4.11  | x        | Started | standard-4.4.11 | Provide OSGi ConfigAdmin support
jaas         | 4.4.11  | x        | Started | standard-4.4.11 | Provide JAAS support
log          | 4.4.11  | x        | Started | standard-4.4.11 | Provide Log support
system       | 4.4.11  | x        | Started | standard-4.4.11 | Provide System support
management   | 4.4.11  | x        | Started | standard-4.4.11 | Provide a JMX MBeanServer
ssh          | 4.4.11  | x        | Started | standard-4.4.11 | Provide a SSHd server on Karaf

Step 5: The default login is rejected

The stock karaf/karaf credential is never shipped. A login with the wrong password fails:

if sshpass -p 'karaf' ssh -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null \
  -o PreferredAuthentications=password -o PubkeyAuthentication=no \
  -o ConnectTimeout=10 -p 8101 karaf@127.0.0.1 'system:version' 2>/dev/null; then
  echo 'UNEXPECTED: default credential accepted'
else
  echo 'default karaf/karaf credential correctly rejected'
fi

Expected output:

default karaf/karaf credential correctly rejected

Step 6: Components

Step 7: Security hardening

• Restrict the NSG so TCP 8101 only reaches your administrative subnets.
• Add more users by editing /opt/karaf/etc/users.properties (user = password,_g_:group lines), or from the console with jaas: commands, then re-log in.
• Deploy applications by dropping OSGi bundles or KAR files into /opt/karaf/deploy, or with bundle:install / feature:install from the console.
• Enable password encryption in /opt/karaf/etc/org.apache.karaf.jaas.cfg (encryption.enabled = true) so users.properties stores hashed passwords.
• Patch regularly: sudo apt-get update && sudo apt-get upgrade && sudo reboot.

Licensing

Apache Karaf is distributed under the Apache-2.0 licence by the Apache Software Foundation — free to use. cloudimg provides the pre-built, hardened image and commercial support separately. cloudimg is not affiliated with or endorsed by the Apache Software Foundation. Questions: support@cloudimg.co.uk.