PK
foeAoa, mimetypeapplication/epub+zipPK
foeA META-INF/PK
foeA OEBPS/PK
foeA
OEBPS/images/PK
foeA OEBPS/imagesdb/PK
foeAh h META-INF/container.xml
The Fuse ESB Enterprise 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 Fuse ESB Enterprise runtime is remotely inaccessible by default.
If you want to access the runtime remotely, you must first customize the security configuration, as described here.
If you want to enable remote access to the Fuse ESB Enterprise container, perform the following configuration steps before starting the container:
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
file and add a new
user field, as follows:InstallDir/etc/users.properties
Username=Password,admin
Where and
Username are the new user credentials. The
Passwordadmin role gives this user the privileges to access all administration and
management functions of the container. For more details about JAAS, see Configuring JAAS Security.
![]() | Warning |
|---|---|
It is strongly recommended that you define custom user credentials with a strong password. |
If you want to access the Apache ActiveMQ Web console (for remote administration of JMS messaging), you must provide the Web console servlet with the credentials it needs to login to the JMS broker.
Edit the file
and modify the InstallDir/etc/system.propertieswebconsole.jmx.* and webconsole.jms.* properties as
follows:
webconsole.jmx.user=Usernamewebconsole.jmx.password=Passwordwebconsole.jms.user=Usernamewebconsole.jms.password=Password
Where the and
Username are the credentials of a JAAS user with
Passwordadmin privileges.
Figure 3.1 shows the ports exposed by the Fuse ESB Enterprise container by default.
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 SSL.
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 Jetty container that can host Web console servlets. By default, the Web consoles are not installed in the container.
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 Fuse ESB Enterprise 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 -uUsername-pPassword
Where the and
Username are the credentials of a JAAS user with
Passwordadmin privileges. For more details, see Using Remote Connections to Manage a Container.
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,
, with a custom key
pair).InstallDir/etc/host.key
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:
service:jmx:rmi:///jndi/rmi://localhost:1099/karaf-root
You must also provide valid JAAS credentials to the JMX client in order to connect.
![]() | Note |
|---|---|
In general, the tail of the JMX URI has the format
|
All of the Web consoles are installed as servlets in the container's embedded Jetty container. The Web consoles share the same HTTP server port, which is powered by Jetty. You can optionally enable the following Web consoles in Fuse ESB Enterprise:
Karaf Web console—is not installed by default. To enable the Karaf Web console, perform the following steps:
In a running Fuse ESB Enterprise instance (see Starting Fuse ESB Enterprise), enter the following console command:
karaf@root> features:install webconsole
In a Web browser, navigate to the following URL:
http://localhost:8181/system/console
The browser will prompt you to log on. Enter valid JAAS user credentials to access the console.
Apache ActiveMQ Web console—is not installed by default. To enable the Apache ActiveMQ Web console, perform the following steps:
Make sure that you have already configured the container's Java system properties, as described in Configure the Apache ActiveMQ Web console (optional).
![]() | Note |
|---|---|
The Apache ActiveMQ Web console has a three tier architecture, as shown in Figure 3.1. The credentials provided in this step enable the middle tier (the Web console servlet) to log on to the back-end tier (the Apache ActiveMQ broker). |
In a running Fuse ESB Enterprise instance, enter the following console command:
karaf@root> features:install mq-web-console
In a Web browser, navigate to the following URL:
http://localhost:8181/activemqweb
The browser will prompt you to log on. Enter valid JAAS user credentials to access the console.
The Fuse ESB Enterprise installer generates a service wrapper that can be easily configured to install Fuse ESB Enterprise as a system service.
Installing Fuse ESB Enterprise as a system service is a two step process:
The service wrapper is configured by the
file, which is
located under the ServiceName-wrapper.conf
directory.InstallDir/etc/
There are several settings you may want to change including:
the default environment settings
the properties passed to the JVM
the classpath
the JMX settings
the logging settings
A broker's environment is controlled by three environment variables:
KARAF_HOME—the location of the Fuse ESB Enterprise install
directory.
KARAF_BASE—the root directory containing the configuration and OSGi
data specific to the broker instance.
The configuration for the broker instance is stored in the
directory. Other data relating to the OSGi runtime is also stored beneath the
base directory.KARAF_BASE/conf
KARAF_DATA—the directory containing the logging and persistence
data for the broker.
Example 2.1 shows the default values.
If you want to pass parameters to the JVM, you do so by setting wrapper properties using
the form wrapper.java.additional..
<n><n> is a sequence number that must be distinct for each
parameter.
One of the most useful things you can do by passing additional parameters to the JVM
is to set Java system properties. The syntax for setting a Java system property is
wrapper.java.additional..<n>=-DPropName=PropValue
Example 2.2 shows the default Java properties.
Example 2.2. Default Java System Properties
# JVM # note that n is the parameter number starting from 1. wrapper.java.additional.1=-Dkaraf.home="%KARAF_HOME%" wrapper.java.additional.2=-Dkaraf.base="%KARAF_BASE%" wrapper.java.additional.3=-Dkaraf.data="%KARAF_DATA%" wrapper.java.additional.4=-Dcom.sun.managment.jmxremote wrapper.java.additional.5=-Dkaraf.startLocalConsole=false wrapper.java.additional.6=-Dkaraf.startRemoteShell=true wrapper.java.additional.7=-Djava.endorsed.dirs="%JAVA_HOME%/jre/lib/endorsed;%JAVA_HOME%/lib/endorsed;%KARAF_HOME%/lib/endorsed" wrapper.java.additional.8=-Djava.ext.dirs="%JAVA_HOME%/jre/lib/ext;%JAVA_HOME%/lib/ext;%KARAF_HOME%/lib/ext"
You add classpath entries using the syntax
wrapper.java.classpath..
<n><n> is a sequence number that must be distinct for each
classpath entry.
Example 2.3 shows the default classpath entries.
The default service wrapper configuration does not enable JMX. It does, however, include template properties for enabling JMX. To enable JMX:
Locate the line # Uncomment to enable jmx.
There are three properties, shown in Example 2.4, that are used to configure JMX.
Remove the # from in front of each of the properties.
Replace the n in each property to a number that fits into the sequence
of addition properties established in the configuration.
You can change the settings to use a different port or secure the JMX connection.
For more information about using JMX see Configuring JMX.
The wrapper's logging in configured using the properties described in Table 2.1.
Table 2.1. Wrapper Logging Properties
| Property | Description |
|---|---|
wrapper.console.format |
Specifies how the logging information sent to the console is formated. The format consists of the following tokens:
|
wrapper.console.loglevel | Specifies the logging level displayed on the console. |
wrapper.logfile | Specifies the file used to store the log. |
wrapper.logfile.format | Specifies how the logging information sent to the log file is formated. |
wrapper.console.loglevel | Specifies the logging level sent to the log file. |
wrapper.console.maxsize | Specifies the maximum size, in bytes, that the log file can grow to before the log is archived. The default value of 0 disables log rolling. |
wrapper.console.maxfiles | Specifies the maximum number of archived log files which will be allowed before old files are deleted. The default value of 0 implies no limit. |
wrapper.syslog.loglevel | Specifies the logging level for the sys/event log output. |
For more information about Fuse ESB Enterprise logging see Logging.
The operating system determines the exact steps using to complete the installation of Fuse ESB Enterprise as a service. The wrapper:install command provides basic instructions for your operating system.
To install the service run
.
If you used the default start setting, the service will start when Windows is
launched. If you specified InstallDir\bin\ServiceName-service.bat installDEMAND_START, you will need to start the service
manually.
To start the service manually run
net start ". You can also use
the Windows service UI.ServiceName"
To manually stop the service run
net stop " You can also use
the Windows service UI.ServiceName"
You remove the installed the service by running
.InstallDir\bin\ServiceName-service.bat remove
To install the service and configure it to start when the machine boots, run the following commands:
#ln -sInstallDir\bin\ServiceName-service /etc/init.d/#chkconfigServiceName-service --add#chkconfigServiceName-service on
To start the service manually run
service .ServiceName-service start
To manually stop the service run
service .ServiceName-service stop
You remove the installed the service by running the following commands:
#serviceServiceName-service stop#chkconfigServiceName-service --del#rm /etc/init.d/ServiceName-service
To install the service and configure it to start when the machine boots, run the following commands:
#ln -sInstallDir\bin\ServiceName-service /etc/init.d/#update-rc.dServiceName-service defaults
To start the service manually run
/etc/init.d/.ServiceName-service start
To manually stop the service run
/etc/init.d/.ServiceName-service stop
You remove the installed the service by running the following commands:
#/etc/init.d/ServiceName-service stop#rm /etc/init.d/ServiceName-service
This chapter describes the basic steps to configure security before you start Fuse ESB Enterprise for the first time. By default, Fuse ESB Enterprise is secure, but none of its services are remotely accessible. This chapter explains how to enable secure access to the ports exposed by Fuse ESB Enterprise.
The OSGi Configuration Admin service specifies the configuration information for deployed services and ensures that the services receive that data when they are active.
A configuration is a list of name-value pairs read from a .cfg file
in the directory. The file is
interpreted using the Java properties file format. The filename is mapped to the persistent
identifier (PID) of the service that is to be configured. In OSGi, a PID is used to identify
a service across restarts of the container. InstallDir/etc
You can configure the Fuse ESB Enterprise runtime using the following files:
Table 7.1. Fuse ESB Enterprise Configuration Files
| Filename | Description |
|---|---|
activemq.xml | Configures the defaultApache ActiveMQ broker in a Fabric (used in combination with the
org.fusesource.mq.fabric.server-default.cfg file). |
config.properties | The main configuration file for the container See Setting OSGi Framework and Initial Container Properties for details. |
org.apache.aries.transaction.cfg | Configures the transaction feature |
org.apache.felix.fileinstall-deploy.cfg | Configures a watched directory and polling interval for hot deployment. |
org.apache.karaf.features.cfg | Configures a list of feature repositories to be registered and a list of features to be installed when Fuse ESB Enterprise starts up for the first time. |
org.apache.karaf.features.obr.cfg | Configures the default values for the features OSGi Bundle Resolver (OBR). |
org.apache.karaf.jaas.cfg | Configures options for the Karaf JAAS login module. Mainly used for configuring encrypted passwords (disabled by default). |
org.apache.karaf.log.cfg | Configures the output of the log console commands. See Logging Configuration. |
org.apache.karaf.management.cfg |
Configures the JMX system. See Configuring JMX for details. |
org.apache.karaf.shell.cfg |
Configures the properties of remote consoles. For more information see Configuring a Container for Remote Access. |
org.apache.servicemix.jbi.cfg |
Configures the shutdown timeout for the JBI container. |
org.apache.servicemix.nmr.cfg |
Configures the default thread pool settings for JBI. See Old Mechanism not supported. |
org.apache.servicemix.components. |
Configures the thread pool settings specifically for the
|
org.fusesource.fabric.fab.osgi.url.cfg | Configures the Maven repositories used by the Fuse Application Bundle (FAB)
runtime when downloading artifacts. If the properties in this file are not set, FAB
defaults to the values in org.ops4j.pax.url.mvn.cfg. |
org.fusesource.fabric.maven.cfg | Configures the Maven repositories used by the Fabric Maven Proxy when downloading artifacts, (The Fabric Maven Proxy is used for provisioning new containers on a remote host.) |
org.fusesource.mq.fabric.server-default.cfg | Configures the defaultApache ActiveMQ broker in a Fabric (used in combination with the
activemq.xml file). |
org.ops4j.pax.logging.cfg |
Configures the logging system. For more, see Logging Configuration. |
org.ops4j.pax.url.mvn.cfg | Configures additional URL resolvers. |
org.ops4j.pax.web.cfg | Configures the default Jetty container (Web server). See Securing the Web Console in Security Guide. |
|
| Specifies which bundles are started in the container and their start-levels.
Entries take the format
bundle=start-level. |
system.properties |
Specifies Java system properties. Any properties set in this file are
available at runtime using |
users.properties | Lists the users who can access the Fuse ESB Enterprise runtime either remotely or via the web
console. The file's contents take the format
username=password,role |
The file naming convention for configuration files depends on whether the configuration is intended for an OSGi Managed Service or for an OSGi Managed Service factory.
The configuration file for an OSGi Managed Service obeys the following naming convention:
<PID>.cfg
Where <PID> is the persistent ID of the OSGi
Managed Service (as defined in the OSGi Configuration Admin specification). A persistent ID
is normally dot delimited—for example, org.ops4j.pax.web.
The configuration file for an OSGi Managed Service Factory obeys the following naming convention:
<PID>-<InstanceID>.cfg
Where <PID> is the persistent ID of the OSGi
Managed Service Factory. In the case of a managed service factory's <PID>,
you can append a hyphen followed by an arbitrary instance ID, <InstanceID>.
The managed service factory then creates a unique service instance for each
<InstanceID> that it finds.
In
addition to the container's configuration files, the
folder may contain a
number of configuration files for the JBI components that ship with Fuse ESB Enterprise. InstallDir/etc
The
component configuration files are named using the scheme
org.apache.servicemix.components..
For example, you would configure the JMS component using a file called
ComponentName.cfgorg.apache.servicemix.components.jms.cfg.
The contents of a component's configuration file is largely component specific. However, each component configuration file contains properties for configuring the thread pool used by the component to process message exchanges. See Configuring JBI Component Thread Pools for details.
A child container is a container that shares a common Fuse ESB Enterprise runtime with a parent container, but has its own configuration files, runtime information, logs and temporary files. The child container functions as an independent container into which you can deploy bundles.
You create a new child container using the fabric:container-create-child
console command, which has the following syntax:
karaf@root> fabric:container-create-childparentchild[number]
Where parent is the name of an existing container in the
fabric and child is the name of the new child container. If you
create multiple child containers (by specifying the optional
number argument), the new child instances are named
,
child1, and so on.child2
For example, assuming the container, root, already belongs to your fabric, you can create two new child containers as follows:
karaf@root> fabric:container-create-child root child 2 The following containers have been created successfully: child1 child2
To list all of the containers in the current fabric (including child instances), use
the fabric:container-list console command. For example:
FuseESB@root> fabric:container-list [id] [version] [alive] [profiles] [provision status] root 1.0 true fabric, fabric-ensemble-0000-1 child1 1.0 true default success child2 1.0 true default success
By default, a child is assigned the default profile when it is created.
To assign a new profile (or profiles) to a child container after it has been created, use the
fabric:container-change-profile console command.
![]() | Tip |
|---|---|
You can assign a profile other than |
For example, to assign the example-camel profile to the
child1 container, enter the following console command:
FuseESBf@root> fabric:container-change-profile child1 example-camel
The command removes the profiles currently assigned to child1 and
replaces them with the specified list of profiles (where in this case, there is just one
profile in the list, example-camel).
To connect to a child container, use the fabric:container-connect console
command. For example, to connect to child1, enter the following console
command:
FuseESB@root>fabric:container-connect -u admin -p admin child1
You should see output like the following in your console window:
Connecting to host YourHost on port 8102 Connected ______ _____ _____ ______ | ___| | ___|/ ___|| ___ \ | |_ _ _ ___ ___ | |__ \ `--. | |_/ / | _|| | | |/ __| / _ \ | __| `--. \| ___ \ | | | |_| |\__ \| __/ | |___ /\__/ /| |_/ / \_| \__,_||___/ \___| \____/ \____/ \____/ Fuse ESB (7.0.0.fuse-beta-039) http://fusesource.org/esb/ Hit '<tab>' for a list of available commands and '[cmd] --help' for help on a specific command. Hit '<ctrl-d>' or 'osgi:shutdown' to shutdown Fuse ESB. FuseESB:admin@child1>
To terminate the session, enter Ctrl-D.
To start a child container that was previously stopped, use the
fabric:container-start command, providing the child container's
name as the command argument—for example, to restart child1:
FuseESB@root>fabric:container-start child1
This command starts up the child in a separate JVM.
To stop a child instance, use the fabric:container-stop command,
providing the child container's name as the command argument—for example, to stop
child1:
FuseESB@root>fabric:container-stop child1
This command kills the JVM process that hosts the child1
container.
To completely destroy a child container use the
fabric:container-delete command. For example, to destroy the
child1 container instance, enter the following console command:
FuseESB@root> fabric:container-delete child1
Destroying a child container does the following:
stops the child's JVM process
physically removes all files related to the child container
The admin console commands allow you to create and manage instances of the Fuse ESB Enterprise runtime on the same machine. Each new runtime is a child instance of the runtime that created it. You can easily manage the children using names instead of network addresses. For details on the admin commands, see Admin Console Commands in Console Reference.
You create a new runtime container by typing admin:create in the
Fuse ESB Enterprise console.
As shown in Example 6.1,
admin:create causes the container to create a new child container
in the active container's instances/
directory. The new container is a direct copy of its parent. The only difference between parent and child
is the port number they listen on. The child container is assigned an SSH port number based
on an incremental count starting at 8101.containerName
Example 6.1. Creating a Runtime Instance
FuseESB@root>admin:create finnCreating new instance on port 8106 at: /home/fuse/esb4/instances/finn Creating dir: /home/fuse/esb4/instances/finn/bin Creating dir: /home/fuse/esb4/instances/finn/etc Creating dir: /home/fuse/esb4/instances/finn/system Creating dir: /home/fuse/esb4/instances/finn/deploy Creating dir: /home/fuse/esb4/instances/finn/data Creating file: /home/fuse/esb4/instances/finn/etc/config.properties Creating file: /home/fuse/esb4/instances/finn/etc/java.util.logging.properties Creating file: /home/fuse/esb4/instances/finn/etc/org.apache.felix.fileinstall-deploy.cfg Creating file: /home/fuse/esb4/instances/finn/etc/org.apache.karaf.log.cfg Creating file: /home/fuse/esb4/instances/finn/etc/org.apache.karaf.features.cfg Creating file: /home/fuse/esb4/instances/finn/etc/org.apache.karaf.management.cfg Creating file: /home/fuse/esb4/instances/finn/etc/org.ops4j.pax.logging.cfg Creating file: /home/fuse/esb4/instances/finn/etc/org.ops4j.pax.url.mvn.cfg Creating file: /home/fuse/esb4/instances/finn/etc/startup.properties Creating file: /home/fuse/esb4/instances/finn/etc/system.properties Creating file: /home/fuse/esb4/instances/finn/etc/org.apache.karaf.shell.cfg Creating file: /home/fuse/esb4/instances/finn/bin/karaf Creating file: /home/fuse/esb4/instances/finn/bin/start Creating file: /home/fuse/esb4/instances/finn/bin/stop
You can change the SSH port number assigned to a child container using the admin:change-port command. The syntax for the command is:
admin:change-port {containerName} {portNumber}
![]() | Important |
|---|---|
You can only use the admin:change-port command on stopped containers. |
New containers are created in the stopped state. To start a child container and make it
ready to host applications, use the admin:start command. This command
takes a single argument, containerName, that identifies the
child you want started.
To see a list of all Fuse ESB Enterprise containers running under a particular installation, use the admin:list command:
You can connect to a started child container's remote console using the admin:connect command.As shown in Example 6.3, this command takes three arguments:
containerName
The name of the child to which you want to connect.
-u
username
The username used to connect to the child's remote console. Use valid JAAS user credentials that have admin privileges (see Configuring JAAS Security).
-p
password
This argument specifies the password used to connect to the child's remote console.
Once you are connected to the child container., the prompt changes to display the name of the current instance, as shown:
FuseESB@harry>To stop a child container, from within the container itself, type
osgi:shutdown or simply shutdown.
To stop a child container remotely—in other words, from a parent or sibling
instance—type admin:stop
.containerName
You can permanently delete a stopped child container using the
admin:destroy
containerName command.
![]() | Important |
|---|---|
You can only remove stopped children. |
You can also use manage an Fuse ESB Enterprise container running in server mode without starting a
new instance of the runtime. The admin script in the
directory provides the
all of the admin console commands except for
admin:connect.InstallDir/bin
Example 6.4. The admin Script
admin.bat: Ignoring predefined value for KARAF_HOME
Available commands:
change-port - Changes the port of an existing container instance.
create - Creates a new container instance.
destroy - Destroys an existing container instance.
list - List all existing container instances.
start - Starts an existing container instance.
stop - Stops an existing container instance.
Type 'command --help' for more help on the specified command.For example, to list all of the Fuse ESB Enterprise containers on your host machine, type:
Windows
admin.bat list*NIX
./admin listFuse ESB Enterprise uses the OSGi Configuration Admin service to manage the configuration of OSGi services. How you feed information to the configuration service depends on how the container is deployed.
The command console's config shell provides commands for editing the configuration of a standalone container. The commands allow you to inspect the container's configuration, add new PIDs, and edit the properties of any PID used by the container. These configuration changes are applied directly to the container and will persist across container restarts.
For more details on the config commands see Config Console Commands in Console Reference.
The config:list command will show all of the PIDs currently in use by the container. As shown in Example 7.1, the output from config:list contains all of the PIDs and all of the properties for each of the PIDs.
Example 7.1. Output of the config:list Command
...
----------------------------------------------------------------
Pid: org.ops4j.pax.logging
BundleLocation: mvn:org.ops4j.pax.logging/pax-logging-service/1.4
Properties:
log4j.appender.out.layout.ConversionPattern = %d{ABSOLUTE} | %-5.5p | %-16.16
t | %-32.32c{1} | %-32.32C %4L | %m%n
felix.fileinstall.filename = org.ops4j.pax.logging.cfg
service.pid = org.ops4j.pax.logging
log4j.appender.stdout.layout.ConversionPattern = %d{ABSOLUTE} | %-5.5p | %-16
.16t | %-32.32c{1} | %-32.32C %4L | %m%n
log4j.appender.out.layout = org.apache.log4j.PatternLayout
log4j.rootLogger = INFO, out, osgi:VmLogAppender
log4j.appender.stdout.layout = org.apache.log4j.PatternLayout
log4j.appender.out.file = C:\apache\apache-servicemix-7.0.2.fuse-097/data/log/karaf.log
log4j.appender.stdout = org.apache.log4j.ConsoleAppender
log4j.appender.out.append = true
log4j.appender.out = org.apache.log4j.FileAppender
----------------------------------------------------------------
Pid: org.ops4j.pax.web
BundleLocation: mvn:org.ops4j.pax.web/pax-web-runtime/0.7.1
Properties:
org.apache.karaf.features.configKey = org.ops4j.pax.web
service.pid = org.ops4j.pax.web
org.osgi.service.http.port = 8181
----------------------------------------------------------------
...Listing the container's configuration is a good idea before editing a container's configuration. You can use the output to ensure that you know the exact PID to change.
Editing a container's configuration involves a number of commands and must be done in the proper sequence. Not following the proper sequence can lead to corrupt configurations or the loss of changes.
To edit a container's configuration:
Start an editing session by typing
config:edit .PID
PID is the PID for the configuration you are editing.
It must be entered exactly. If it does not match the
desired PID, the container will create a new PID with the specified name.
Remind yourself of the available properties in a particular configuration by typing
config:proplist.
Use one of the editing commands to change the properties in the configuration.
The editing commands include:
config:propappend—appends a new property to the configuration
config:propset—set the value for a configuration property
config:propdel—delete a property from the configuration
Update the configuration in memory and save it to disk by typing
config:update.
![]() | Note |
|---|---|
To exit the configuration, without saving your changes,
type |
Example 7.2 shows a configuration editing session that changes a container's logging behavior.
Example 7.2. Editing a Configuration
FuseESB@root>config:edit org.apache.karaf.logFuseESB@root>config:proplistservice.pid = org.apache.karaf.log size = 500 felix.fileinstall.filename = org.apache.karaf.log.cfg pattern = %d{ABSOLUTE} | %-5.5p | %-16.16t | %-32.32c{1} | %-32.32C %4L | %m%nFuseESB@root>config:propset size 300FuseESB@root>config:update
When a container is part of a fabric, it does not manage its configuration. The container's configuration is managed by the Fabric Agent. The agent runs along with the container and updates the container's configuration based on information from the fabric's registry.
Because the configuration is managed by the Fabric Agent, any changes to the container's configuration needs to be done by updating the fabric's registry. In a fabric, container configuration is determined by one or more profiles that are deployed into the container. To change a container's configuration, you must update the profile(s) deployed into the container using either the console's fabric: shell or Fuse Management Console.
All configuration in a fabric is stored as profiles in the Fabric Registry. One or more profiles are assigned to containers that are part of the fabric. A profile is a collection of configuration that specifies:
the Apache Karaf features to be deployed
OSGi bundles to be deployed
the feature repositories to be scanned for features
properties that configure the container's runtime behavior
The configuration profiles are collected into versions. Versions are typically used to make updates to an existing profile without effecting deployed containers. When a container is configured it is assigned a profile version from which it draws the profiles. Therefore, when you create a new version and edit the profiles in the new version, the profiles that are in use are not changed. When you are ready to test the changes, you can roll them out incrementally by moving containers to a new version one at a time.
When a container joins a fabric, a Fabric Agent is deployed with the container and takes control of the container's configuration. The agent will ask the Fabric Registry what version and profile(s) are assigned to the container and configure the container based on the profiles. The agent will download and install of the specified bundles and features. It will also set all of the specified configuration properties.
Editing a profile makes changes to the copy in the Fabric Registry and all of the Fabric Agents are alerted when changes are made. If a running container is using a profile that is changed, its agent will automatically apply the new settings. If the update is benign having the change rolled out to the entire fabric is not an issue. If, on the other hand, the change causes issues, the entire fabric could become unstable.
To avoid having untested changes infecting an entire fabric, you should always make a new version before editing a profile. This isolates the changes in a version that is not running on any containers and provides a quick backup in case the changes are bad.
Once the profile changes have been made, you should test them out by upgrading only a few containers to the new version to see how they behave. As you become confident that the changes are good, you can then upgrade more containers.
The command console's fabric shell has commands for managing profiles and versions in a fabric. These commands include:
fabric:version-create—create a new version
fabric:profile-create—create a new profile
fabric:profile-edit—edit the properties in a profile
fabric:container-change-profile—change the profiles assigned to a container
Example 7.3 shows a session for updating a profile using the command console.
Example 7.3. Editing Fabric Profile
FuseESB:karaf@root>fabric:version-createCreated version: 1.1 as copy of: 1.0FuseESB:karaf@root>fabric:profile-edit -p org.apache.karaf.log/size=300 NEBroker
The change made in Example 7.3 is not applied to any running containers because it is made in a new version. In order to apply the change you need to update one or more containers using the fabric:container-upgrade command.
See Fabric Console Commands in Console Reference for more information.
Fuse Management Console simplifies the process of configuring containers in a fabric by providing an easy to use Web-based interface and reducing the number of steps required to make the changes. For more information on using Fuse Management Console see the Fuse Management Console Documentation.
The remote client allows you to securely connect to a remote Fuse ESB Enterprise container without having to launch a full Fuse ESB Enterprise container locally.
For example, to quickly connect to a Fuse ESB Enterprise instance running in server mode on the same
machine, open a command prompt and run the client[.bat] script
(which is located in the
directory), as follows:InstallDir/bin
clientMore usually, you would provide a hostname, port, username, and password to connect to a remote instance. If you were using the client within a larger script, for example in a test suite, you could append console commands as follows:
client -a 8101 -h hostname -u username -p password shell:infoFor a standalone container, use any valid JAAS
user credentials that have admin privileges.
For a container in a fabric, the default username and password
is admin and admin.
To display the available options for the client, type:
client --helpExample 5.8. Karaf Client Help
Apache Felix Karaf client
-a [port] specify the port to connect to
-h [host] specify the host to connect to
-u [user] specify the user name
-p [password] specify the password
--help shows this help message
-v raise verbosity
-r [attempts] retry connection establishment (up to attempts times)
-d [delay] intra-retry delay (defaults to 2 seconds)
[commands] commands to run
If no commands are specified, the client will be put in an interactive modeIf you used the remote client to open a remote console, as opposed to using it to pass a command, you will need to disconnect from it. To disconnect from the remote client's console, enter logout or press Ctrl+D at the prompt.
The client will disconnect and exit.
When containers are deployed into a fabric, they are all connected to each other. You can easily connect to any container's command console from any of it's fabric mates. Connecting using fabric does not require knowing any of the remote containers SSH details. The fabric's runtime registry has all of the details needed to establish the remote connection.
In the context of a fabric, you should connect to a remote runtime's console using the fabric:container-connect command.
Example 5.5. fabric:container-connect Command Syntax
fabric:container-connect {-u username} {-p password} {containerName}
-u username
The username used to connect to the remote console. The default value is
admin.
-p password
The password used to connect to the remote console. The default value is
admin.
containerName
The name of the container.
![]() | Warning |
|---|---|
We recommend that you change the default administrator username and password. See Configuring JAAS Security for details. |
Example 5.6. Connecting to a Remote Container
karaf@root>fabric:container-connect -u admin -p admin containerNameTo confirm that you have connected to the correct container, type
shell:info at the prompt. Information about
the currently connected instance is returned, as shown in Example 5.7.
Example 5.7. Output of the shell:info Command
Karaf
Karaf version 2.2.5.fuse-beta-7-052
Karaf home /Volumes/ESB/fuse-esb-7.0.2.fuse-097
Karaf base /Volumes/ESB/fuse-esb-7.0.2.fuse-097
OSGi Framework org.apache.felix.framework - 4.0.3.fuse-beta-7-052
JVM
Java Virtual Machine Java HotSpot(TM) 64-Bit Server VM version 20.6-b01-415
Version 1.6.0_31
Vendor Apple Inc.
Uptime 6 minutes
Total compile time 24.048 seconds
Threads
Live threads 62
Daemon threads 43
Peak 287
Total started 313
Memory
Current heap size 78,981 kbytes
Maximum heap size 466,048 kbytes
Committed heap size 241,920 kbytes
Pending objects 0
Garbage collector Name = 'PS Scavenge', Collections = 11, Time = 0.271 seconds
Garbage collector Name = 'PS MarkSweep', Collections = 1, Time = 0.117 seconds
Classes
Current classes loaded 5,720
Total classes loaded 5,720
Total classes unloaded 0
Operating system
Name Mac OS X version 10.7.3
Architecture x86_64
Processors 2Any container's command console can be used to access a remote container. Using SSH, the local container's console connects to the remote container and functions as a command console for the remote container.
You connect to a remote container's console using the ssh:ssh console command.
-l username
The username used to connect to the remote container. Use valid JAAS login
credentials that have admin privileges (see Configuring JAAS Security).
-P password
The password used to connect to the remote container.
-p port
The SSH port used to access the desired container's remote console.
By default this value is 8101. See
Configuring a standalone container for remote access for details on changing the
port number.
hostname
The hostname of the machine that the remote container is running on. See Configuring a standalone container for remote access for details on changing the hostname.
![]() | Warning |
|---|---|
We recommend that you customize the username and password in the |
To confirm that you have connected to the correct container, type
shell:info at the prompt. Information about the currently
connected instance is returned, as shown in Example 5.4.
Example 5.4. Output of the shell:info Command
Karaf
Karaf version 2.2.5.fuse-beta-7-052
Karaf home /Volumes/ESB/fuse-esb-7.0.2.fuse-097
Karaf base /Volumes/ESB/fuse-esb-7.0.2.fuse-097
OSGi Framework org.apache.felix.framework - 4.0.3.fuse-beta-7-052
JVM
Java Virtual Machine Java HotSpot(TM) 64-Bit Server VM version 20.6-b01-415
Version 1.6.0_31
Vendor Apple Inc.
Uptime 6 minutes
Total compile time 24.048 seconds
Threads
Live threads 62
Daemon threads 43
Peak 287
Total started 313
Memory
Current heap size 78,981 kbytes
Maximum heap size 466,048 kbytes
Committed heap size 241,920 kbytes
Pending objects 0
Garbage collector Name = 'PS Scavenge', Collections = 11, Time = 0.271 seconds
Garbage collector Name = 'PS MarkSweep', Collections = 1, Time = 0.117 seconds
Classes
Current classes loaded 5,720
Total classes loaded 5,720
Total classes unloaded 0
Operating system
Name Mac OS X version 10.7.3
Architecture x86_64
Processors 2There are two options for how to create a fabric from a standalone container:
The recommended approach is to create the fabric such that the container is converted into a managed Fabric Server. The container's existing configuration will be reset, so you will need to create a profile for the container's original configuration and associate it with a new container.
The alternative approach is to create the fabric such that the container becomes a non-managed Fabric Server. The container becomes a Fabric Server that is fully capable of being part of a fabric's ensemble. However, the container retains control over its own configuration. It will continue to be managed as if it were a standalone container and will not respond to fabric commands that attempt to alter its configuration.
Several things happen when a fabric is created from a standalone container:
The container installs the required Fuse Fabric bundles to become a Fabric Server.
The Fabric Server starts up the ensemble process.
A new ensemble containing an empty configuration registry and a runtime registry with a single entry for the Fabric Server is created.
The Fabric Server delegates control over its configuration to the ensemble.
This process clears the container and resets its configuration to a default state.
![]() | Note |
|---|---|
If the fabric is created with a non-managed server, this step is skipped. |
The ensemble associates the profiles required to be a Fabric Server with the container.
Unless the --no-import flag is used, the ensemble imports a set of
profiles.
If the --import-dir flag is used, the profiles are imported
from the specified location.
If no location is specified the default set of profiles is imported from
.InstallDir/fabric/import
The ensemble waits for commands to update the fabric.
To create a new fabric from a standalone container:
Connect to the standalone container's command console.
Enter the following command:
FuseESB:karaf@root>fabric:create
![]() | Tip |
|---|---|
If you want to import a predefined set of profiles, use the
|
For details on fabric:create see fabric:create in Console Reference.
Any standalone container can be joined to an existing fabric using the fabric:join. You need to supply the URL of one of the Fuse Servers in the fabric and the standalone container is added to the fabric. The container can join the fabric as either a managed container or a non-managed container:
A managed container is a full member of the fabric and is managed by a Fabric Agent. The agent configures the container based on information provided by the fabric's ensemble. The ensemble knows which profiles are associated with the container and the agent determines what to install based on the contents of the profiles.
A non-managed container is not managed by a Fabric Agent. It's configuration remains intact after it joins the fabric and is controlled as if the container were a standalone container. Joining the fabric in this manner registers the container with the fabric's ensemble and allows clients to locate the services running in the container using the fabric's discovery mechanism.