Chapter 3. Basic Security

This chapter describes the basic steps to configure security before you start Karaf for the first time. By default, Karaf is secure, but none of its services are remotely accessible. This chapter explains how to enable secure access to the ports exposed by Karaf.

3.1. Configuring Basic Security

3.1.1. Overview

The Apache Karaf runtime is secured against network attack by default, because all of its exposed ports require user authentication and no users are defined initially. In other words, the Apache Karaf runtime is remotely inaccessible by default.

If you want to access the runtime remotely, you must first customize the security configuration, as described here.

3.1.2. Before you start the container

If you want to enable remote access to the Karaf container, you must create a secure JAAS user before starting the container:

3.1.3. Create a secure JAAS user

By default, no JAAS users are defined for the container, which effectively disables remote access (it is impossible to log on).

To create a secure JAAS user, edit the InstallDir/etc/ file and add a new user field, as follows:


Where Username and Password are the new user credentials. The admin role gives this user the privileges to access all administration and management functions of the container.

Do not define a numeric username with a leading zero. Such usernames will always cause a login attempt to fail. This is because the Karaf shell, which the console uses, drops leading zeros when the input appears to be a number. For example:

karaf@root> echo 0123
karaf@root> echo 00.123

It is strongly recommended that you define custom user credentials with a strong password.

3.1.4. Role-based access control

The Karaf container supports role-based access control, which regulates access through the JMX protocol, the Karaf command console, and the Fuse Management console. When assigning roles to users, you can choose from the set of standard roles, which provide the levels of access described in Table 3.1, “Standard Roles for Access Control”.

Table 3.1. Standard Roles for Access Control



Grants read-only access to the container.


Grants read-write access at the appropriate level for ordinary users, who want to deploy and run applications. But blocks access to sensitive container configuration settings.


Grants unrestricted access to the container.


Grants permission for remote console access through the SSH port.

For more details about role-based access control, see Role-Based Access Control.

3.1.5. Ports exposed by the Apache Karaf container

The following ports are exposed by the container:

  • Console port — enables remote control of a container instance, through Apache Karaf shell commands. This port is enabled by default and is secured both by JAAS authentication and by SSH.
  • JMX port — enables management of the container through the JMX protocol. This port is enabled by default and is secured by JAAS authentication.
  • Web console port — provides access to an embedded Undertow container that can host Web console servlets. By default, the Fuse Console is installed in the Undertow container.

3.1.6. Enabling the remote console port

You can access the remote console port whenever both of the following conditions are true:

  • JAAS is configured with at least one set of login credentials.
  • The Karaf runtime has not been started in client mode (client mode disables the remote console port completely).

For example, to log on to the remote console port from the same machine where the container is running, enter the following command:

./client -u Username -p Password

Where the Username and Password are the credentials of a JAAS user with the ssh role. When accessing the Karaf console through the remote port, your privileges depend on the roles assigned to the user in the etc/ file. If you want access to the complete set of console commands, the user account must have the admin role.

3.1.7. Strengthening security on the remote console port

You can employ the following measures to strengthen security on the remote console port:

  • Make sure that the JAAS user credentials have strong passwords.
  • Customize the X.509 certificate (replace the Java keystore file, InstallDir/etc/host.key, with a custom key pair).

3.1.8. Enabling the JMX port

The JMX port is enabled by default and secured by JAAS authentication. In order to access the JMX port, you must have configured JAAS with at least one set of login credentials. To connect to the JMX port, open a JMX client (for example, jconsole) and connect to the following JMX URI:


You must also provide valid JAAS credentials to the JMX client in order to connect.


In general, the tail of the JMX URI has the format /karaf-ContainerName. If you change the container name from root to some other name, you must modify the JMX URI accordingly.

3.1.9. Strengthening security on the Fuse Console port

The Fuse Console is already secured by JAAS authentication. To add SSL security, see Securing the Undertow HTTP Server.