Apache Karaf OSGi Runtime on AWS 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. Deploy applications as OSGi bundles or higher-level Karaf features, drop artifacts into the deploy directory to hot-deploy them, and administer the whole runtime interactively over a secure SSH console.

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 instance's first boot, so no two deployments share a password and nothing is baked into the Amazon Machine 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
• A per-instance karaf console credential rotated at first boot into etc/users.properties
• The default karaf/karaf credential removed; wrong-credential logins rejected
• A per-instance SSH host key for the console, generated at first boot
• apache-karaf.service running as an unprivileged karaf user
• A hardened, fully patched base operating system
• 24/7 cloudimg support

Prerequisites

• An EC2 instance launched from this cloudimg AMI (recommended type m5.large or larger; Karaf is a JVM runtime, so give it adequate memory)
• A security group allowing inbound TCP 22 (SSH) from your admin network, and TCP 8101 (the Karaf console) opened only to your trusted operator network
• An SSH client on your workstation, plus sshpass if you want to script console logins

The recommended security group opens only SSH (port 22). The Karaf console on TCP 8101 is deliberately not opened to the internet. Add an inbound rule for TCP 8101 scoped to your administrative CIDR only. Never expose the Karaf console to the whole internet.

Connecting to your instance

SSH to the instance as the default login user for the operating-system variant you launched:

ssh ubuntu@<public-ip>

Step 1: Verify Karaf is running

SSH in, 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 Wed 2026-07-22 04:29:46 UTC; 3min 18s ago
       Docs: https://www.cloudimg.co.uk/guides/apache-karaf-aws/
   Main PID: 2315 (karaf)
      Tasks: 76 (limit: 4520)
     Memory: 302.3M (peak: 302.3M)
LISTEN 0      50                      *:8101             *:*

Step 2: Read the per-instance console credential

The karaf username and its randomly generated password are written to a root-only credentials file at first boot. The file is mode 0600 and owned by root, so only root can read it:

sudo ls -l /root/karaf-credentials.txt
sudo stat -c 'perms=%a owner=%U:%G' /root/karaf-credentials.txt

Expected output:

-rw------- 1 root root 623 Jul 22 04:29 /root/karaf-credentials.txt
perms=600 owner=root:root

To read the generated password (keep it private), sudo cat /root/karaf-credentials.txt. The file records KARAF_SSH_USER, KARAF_SSH_PASSWORD, KARAF_SSH_HOST and KARAF_SSH_PORT. Your password is unique to this instance.

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 instance itself:

PASS=$(sudo grep '^KARAF_SSH_PASSWORD=' /root/karaf-credentials.txt | cut -d= -f2-)
sshpass -p "$PASS" ssh -n -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, open TCP 8101 in your security group to your operator CIDR first, then replace 127.0.0.1 with the instance's IP, or use the bundled client: /opt/karaf/bin/client -a 8101 -h <public-ip> -u karaf.

Step 4: List installed features and bundles

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

PASS=$(sudo grep '^KARAF_SSH_PASSWORD=' /root/karaf-credentials.txt | cut -d= -f2-)
sshpass -p "$PASS" ssh -n -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, abbreviated):

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
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

Deploy more capability with feature:install <name> (for example feature:install scr to add Declarative Services), install OSGi bundles with bundle:install, or hot-deploy by dropping a bundle or KAR file into /opt/karaf/deploy.

Step 5: The default login is rejected

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

if sshpass -p 'karaf' ssh -n -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 security group so TCP 8101 only reaches your administrative CIDR. It is not opened to the internet by the recommended security group.
• Deploy in a private subnet and reach the console through a bastion or VPN where possible.
• 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.
• Encrypt at rest by enabling EBS encryption on the instance's volumes.
• Patch regularly: sudo apt-get update && sudo apt-get upgrade && sudo reboot.

Backup and maintenance

• Configuration lives in /opt/karaf/etc; back up that directory to preserve your users, features configuration and any custom *.cfg files.
• Deployed artifacts dropped into /opt/karaf/deploy should be kept in your own source control or artifact repository.
• Upgrades: install OS updates with apt-get, and track new Karaf releases from the Apache project; cloudimg ships updated images as new AMI versions.

Licensing

Apache Karaf is distributed under the Apache-2.0 licence (SPDX Apache-2.0) by the Apache Software Foundation and is 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. All product and company names are trademarks or registered trademarks of their respective holders. Questions: support@cloudimg.co.uk.