-
Language:
English
-
Language:
English
Red Hat Training
A Red Hat training course is available for Red Hat Fuse
Configuring and Running JBoss Fuse
Managing the runtime container
Red Hat
Copyright © 2011-2020 Red Hat, Inc. and/or its affiliates.
Abstract
Chapter 1. Configuring the Initial Features in a Standalone Container
Abstract
Overview
etc/org.apache.karaf.features.cfg
file to discover the feature URLs (feature repository locations) and to determine which features it will load. By default, Red Hat JBoss Fuse loads a large number of features and you may not need all of them. You may also decide you need features that are not included in the default configuration.
etc/org.apache.karaf.features.cfg
are only used the first time the container is started. On subsequent start-ups, the container uses the contents of the InstallDir/data
directory to determine what to load. If you need to adjust the features loaded into a container, you can delete the data
directory, but this will also destroy any state or persistence information stored by the container.
Modifying the default installed features
Modifying the default set of feature URLs
Chapter 2. Installing Red Hat JBoss Fuse as a Service
Abstract
2.1. Overview
bin/contrib
directory.
2.1.1. Running Fuse as a Service
- the init script
- the init configuration file
2.1.2. Customizing karaf-service.sh Utility
Table 2.1.
Command Line Option | Environment Variable | Description |
---|---|---|
-k | KARAF_SERVICE_PATH | Karaf installation path |
-d | KARAF_SERVICE_DATA | Karaf data path (default to \${KARAF_SERVICE_PATH}/data ) |
-c | KARAF_SERVICE_CONF | Karaf configuration file (default to \${KARAF_SERVICE_PATH/etc/\${KARAF_SERVICE_NAME}.conf ) |
-t | KARAF_SERVICE_ETC | Karaf etc path (default to \${KARAF_SERVICE_PATH/etc} ) |
-p | KARAF_SERVICE_PIDFILE | Karaf pid path (default to \${KARAF_SERVICE_DATA}/\${KARAF_SERVICE_NAME}.pid) ) |
-n | KARAF_SERVICE_NAME | Karaf service name (default karaf) |
-e | KARAF_ENV | Karaf environment variable |
-u | KARAF_SERVICE_USER | Karaf user |
-g | KARAF_SERVICE_GROUP | Karaf group (default \${KARAF_SERVICE_USER ) |
-l | KARAF_SERVICE_LOG | Karaf console log (default to \${KARAF_SERVICE_DATA}/log/\${KARAF_SERVICE_NAME}-console.log ) |
-f | KARAF_SERVICE_TEMPLATE | Template file to use |
-x | KARAF_SERVICE_EXECUTABLE | Karaf executable name (defaul karaf support daemon and stop commands) |
CONF_TEMPLATE="karaf-service-template.conf" SYSTEMD_TEMPLATE="karaf-service-template.systemd" SYSTEMD_TEMPLATE_INSTANCES="karaf-service-template.systemd-instances" INIT_TEMPLATE="karaf-service-template.init" INIT_REDHAT_TEMPLATE="karaf-service-template.init-redhat" INIT_DEBIAN_TEMPLATE="karaf-service-template.init-debian" SOLARIS_SMF_TEMPLATE="karaf-service-template.solaris-smf"
2.1.3. Systemd
karaf-service.sh
utility identifies Systemd, it generates three files:
- a systemd unit file to manage the root Apache Karaf container
- a systemd environment file with variables used by the root Apache Karaf container
- a systemd template unit file to manage Apache Karaf child containers
$ ./karaf-service.sh -k /opt/karaf-4 -n karaf-4 Writing service file "/opt/karaf-4/bin/contrib/karaf-4.service" Writing service configuration file ""/opt/karaf-4/etc/karaf-4.conf" Writing service file "/opt/karaf-4/bin/contrib/karaf-4@.service" $ cp /opt/karaf-4/bin/contrib/karaf-4.service /etc/systemd/system $ cp /opt/karaf-4/bin/contrib/karaf-4@.service /etc/systemd/system $ systemctl enable karaf-4.service
2.1.4. SysV
karaf-service.sh
utility identifies a SysV system, it generates two files:
- an init script to manage the root Apache Karaf container
- an environment file with variables used by the root Apache Karaf container
$ ./karaf-service.sh -k /opt/karaf-4 -n karaf-4 Writing service file "/opt/karaf-4/bin/contrib/karaf-4" Writing service configuration file "/opt/karaf-4/etc/karaf-4.conf" $ ln -s /opt/karaf-4/bin/contrib/karaf-4 /etc/init.d/ $ chkconfig karaf-4 on
2.1.5. Solaris SMF
$ ./karaf-service.sh -k /opt/karaf-4 -n karaf-4 Writing service file "/opt/karaf-4/bin/contrib/karaf-4.xml" $ svccfg validate /opt/karaf-4/bin/contrib/karaf-4.xml $ svccfg import /opt/karaf-4/bin/contrib/karaf-4.xml
2.1.6. Windows
- Rename the
karaf-service-win.exe
file tokaraf-4.exe
file. - Rename the
karaf-service-win.xml
file tokaraf-4.xml
file. - Customize the service descriptor as per your requirements.
- Use the service executable to install, start and stop the service.
C:\opt\apache-karaf-4\bin\contrib> karaf-4.exe install C:\opt\apache-karaf-4\bin\contrib> karaf-4.exe start
Chapter 3. Basic Security
Abstract
3.1. Configuring Basic Security
Overview
Before you start the container
Create a secure JAAS user
InstallDir/etc/users.properties
file and add a new user field, as follows:
Username=Password,Administrator
Username
and Password
are the new user credentials. The Administrator
role gives this user the privileges to access all administration and management functions of the container. For more details about JAAS, see Chapter 14, Configuring JAAS Security.
FuseMQ:karaf@root>
echo 0123 123FuseMQ:karaf@root>
echo 00.123 0.123FuseMQ:karaf@root>
Role-based access control
Table 3.1. Standard Roles for Access Control
Roles | Description |
---|---|
Monitor , Operator , Maintainer | Grants read-only access to the container. |
Deployer , Auditor | 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. |
Administrator , SuperUser | Grants unrestricted access to the container. |
Ports exposed by the JBoss Fuse container
Figure 3.1. Ports Exposed by the JBoss Fuse 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 Jetty container that can host Web console servlets. By default, the Fuse Management Console is installed in the Jetty container.
Enabling the remote console port
- JAAS is configured with at least one set of login credentials.
- The JBoss Fuse runtime has not been started in client mode (client mode disables the remote console port completely).
./client -u Username -p Password
Username
and Password
are the credentials of a JAAS user with Administrator
privileges. For more details, see Chapter 8, Using Remote Connections to Manage a Container.
Strengthening 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).
Enabling the JMX port
jconsole
) and connect to the following JMX URI:
service:jmx:rmi:///jndi/rmi://localhost:1099/karaf-root
/karaf-ContainerName
. If you change the container name from root
to some other name, you must modify the JMX URI accordingly.
Strengthening security on the Fuse Management Console port
3.2. Disabling Broker Security
Overview
Standalone server
InstallDir/etc/broker.xml
file using a text editor and look for the following lines:
...
<plugins>
<jaasAuthenticationPlugin configuration="karaf" />
</plugins>
...
jaasAuthenticationPlugin
element. The next time you start up the Red Hat JBoss Fuse container (using the InstallDir/bin/fusemq
script), the broker will run with unsecured ports.
Chapter 4. Starting and Stopping JBoss Fuse
Abstract
4.1. Starting JBoss Fuse
Abstract
Overview
Setting up your environment
bin
subdirectory of your installation, without modifying your environment. However, if you want to start it in a different folder you will need to add the bin
directory of your JBoss Fuse installation to the PATH
environment variable, as follows:
set PATH
=%PATH
%;InstallDir\bin
export PATH
=$PATH
,InstallDir/bin
Launching the runtime in console mode
bin\fuse.bat
./bin/fuse
_ ____ ______ | | _ \ | ____| | | |_) | ___ ___ ___ | |__ _ _ ___ ___ _ | | _ / _ \/ __/ __| | __| | | / __|/ _ \ | |__| | |_) | (_) \__ \__ \ | | | |_| \__ \ __/ \____/|____/ \___/|___/___/ |_| \__,_|___/\___| JBoss Fuse (6.3.0.redhat-xxx) http://www.redhat.com/products/jbossenterprisemiddleware/fuse/ 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 JBoss Fuse. JBossFuse:karaf@root>
./bin/karaf
, which is executing the Karaf console; and the child process, which is executing the Karaf server in a java
JVM. The shutdown behaviour remains the same as before, however. That is, you can shut down the server from the console using either Ctrl-D or osgi:shutdown
, which kills both processes.
Launching the runtime in server mode
bin\start.bat
./bin/start
Launching the runtime in client mode
bin\fuse.bat client
./bin/fuse client
4.2. Stopping JBoss Fuse
Abstract
stop
script.
Stopping an instance from a local console
fuse
or fuse client
, you can stop it by doing one of the following at the karaf>
prompt:
- Type
shutdown
- Press Ctrl+D
Stopping an instance running in server mode
InstallDir/bin
directory, as follows:
bin\stop.bat
./bin/stop
stop
script is similar to the shutdown mechanism implemented in Apache Tomcat. The Karaf server opens a dedicated shutdown port (not the same as the SSH port) to receive the shutdown notification. By default, the shutdown port is chosen randomly, but you can configure it to use a specific port if you prefer.
InstallDir/etc/config.properties
file:
karaf.shutdown.port
- Specifies the TCP port to use as the shutdown port. Setting this property to
-1
disables the port. Default is0
(for a random port). karaf.shutdown.host
- Specifies the hostname to which the shutdown port is bound. This setting could be useful on a multi-homed host. Defaults to
localhost
.NoteIf you wanted to use thebin/stop
script to shut down the Karaf server running on a remote host, you would need to set this property to the hostname (or IP address) of the remote host. But beware that this setting also affects the Karaf server located on the same host as theetc/config.properties
file. karaf.shutdown.port.file
- After the Karaf instance starts up, it writes the current shutdown port to the file specified by this property. The
stop
script reads the file specified by this property to discover the value of the current shutdown port. Defaults to${karaf.data}/port
.NoteIf you wanted to use thebin/stop
script to shut down the Karaf server running on a remote host, you would need to set this property equal to the remote host's shutdown port. But beware that this setting also affects the Karaf server located on the same host as theetc/config.properties
file. karaf.shutdown.command
- Specifies the UUID value that must be sent to the shutdown port in order to trigger shutdown. This provides an elementary level of security, as long as the UUID value is kept a secret. For example, the
etc/config.properties
file could be read-protected to prevent this value from being read by ordinary users.When Apache Karaf is started for the very first time, a random UUID value is automatically generated and this setting is written to the end of theetc/config.properties
file. Alternatively, ifkaraf.shutdown.command
is already set, the Karaf server uses the pre-existing UUID value (which enables you to customize the UUID setting, if required).NoteIf you wanted to use thebin/stop
script to shut down the Karaf server running on a remote host, you would need to set this property to be equal to the value of the remote host'skaraf.shutdown.command
. But beware that this setting also affects the Karaf server located on the same host as theetc/config.properties
file.
Stopping a child container instance
admin
family of console commands (for example, using admin:create
, admin:start
, admin:stop
, and so on). To stop the ChildContainerName
child container running on your local host, invoke the admin(.bat) script from the command line, as follows:
bin\admin.bat stop
ChildContainerName
./bin/admin stop
ChildContainerName
Stopping a remote instance
Chapter 5. Creating a New Fabric
Abstract
Static IP address required for Fabric Server
- For simple examples and tests (with a single Fabric Server) you can work around the static IP requirement by using the loopback address,
127.0.0.1
. - For distributed tests (multiple Fabric Servers) and production deployments, you must assign a static IP address to each of the Fabric Server hosts.
--resolver manualip --manual-ip StaticIPAddress
options to specify the static IP address explicitly, when creating a new Fabric Server.
Make Quickstart Examples Available
$FUSE_HOME/fabric/io.fabric8.import.profiles.properties
file by uncommenting the line that starts with the following:
# importProfileURLs =
- Check that the fabric is running.
- In the
$FUSE_HOME/quickstarts
directory, change to the directory in which the quickstart example you want to run is located, for example:cd beginner
- In that directory, execute the following command:
mvn fabric8:deploy
You would need to run this command in each directory that contains a quickstart example that you want to run.
Procedure
- (Optional) Customise the name of the root container by editing the
InstallDir/etc/system.properties
file and specifying a different name for this property:karaf.name=root
NoteFor the first container in your fabric, this step is optional. But at some later stage, if you want to join a root container to the fabric, you might need to customise the container's name to prevent it from clashing with any existing root containers in the fabric. - Any existing users in the
InstallDir/etc/users.properties
file are automatically used to initialize the fabric's user data, when you create the fabric. You can populate theusers.properties
file, by adding one or more lines of the following form:Username=Password[,RoleA][,RoleB]...
But there must not be any users in this file that have administrator privileges (Administrator
,SuperUser
, oradmin
roles). If theInstallDir/etc/users.properties
already contains users with administrator privileges, you should delete those users before creating the fabric.ImportantIf you leave some administrator credentials in theusers.properties
file, this represents a security risk because the file could potentially be accessed by other containers in the fabric.NoteThe initialization of user data fromusers.properties
happens only once, at the time the fabric is created. After the fabric has been created, any changes you make tousers.properties
will have no effect on the fabric's user data. - If you use a VPN (virtual private network) on your local machine, it is advisable to log off VPN before you create the fabric and to stay logged off while you are using the local container.NoteA local Fabric Server is permanently associated with a fixed IP address or hostname. If VPN is enabled when you create the fabric, the underlying Java runtime is liable to detect and use the VPN hostname instead of your permanent local hostname. This can also be an issue with multi-homed machines.
- Start up your local container.In JBoss Fuse, start the local container as follows:
cd InstallDir/bin ./fuse
- Create a new fabric by entering the following command:
JBossFuse:karaf@root> fabric:create --new-user AdminUser --new-user-password AdminPass --new-user-role Administrator --zookeeper-password ZooPass --resolver manualip --manual-ip StaticIPAddress --wait-for-provisioning
The current container, namedroot
by default, becomes a Fabric Server with a registry service installed. Initially, this is the only container in the fabric. The--new-user
,--new-user-password
, and--new-user-role
options specify the credentials for a newAdministrator
user. The Zookeeper password is used to protect sensitive data in the Fabric registry service (all of the nodes under/fabric
). The--manual-ip
option specifies the Fabric Server's static IP addressStaticIPAddress
(see the section called “Static IP address required for Fabric Server”).For more details on fabric:create see section "fabric:create" in "Console Reference".For more details about resolver policies, see section "fabric:container-resolver-list" in "Console Reference" and section "fabric:container-resolver-set" in "Console Reference".
Fabric creation process
- The container installs the requisite OSGi bundles to become a Fabric Server.
- The Fabric Server starts a registry service, which listens on TCP port 2181 (which makes fabric configuration data available to all of the containers in the fabric).NoteYou can customize the value of the registry service port by specifying the
--zookeeper-server-port
option. - The Fabric Server installs a new JAAS realm (based on the ZooKeeper login module), which overrides the default JAAS realm and stores its user data in the ZooKeeper registry.
- The new Fabric Ensemble consists of a single Fabric Server (the current container).
- A default set of profiles is imported from
InstallDir/fabric/import
(can optionally be overridden). - After the standalone container is converted into a Fabric Server, the previously installed OSGi bundles and Karaf features are completely cleared away and replaced by the default Fabric Server configuration. For example, some of the shell command sets that were available in the standalone container are no longer available in the Fabric Server.
Expanding a Fabric
- Child container, created on the local machine as a child process in its own JVM.Instructions on creating a child container are found in Child Containers.
- SSH container, created on any remote machine for which you have
ssh
access.Instructions on creating a SSH container are found in SSH Containers.
Chapter 6. Joining a Fabric
Overview
- 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. Its 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.
Joining a fabric as a managed container
fabric
profile. If you want to preserve the previous configuration of the container, however, you must ensure that the fabric has an appropriately configured profile, which you can deploy into the container after it joins the fabric.
-p
option enables you to specify a profile to install into the container once the agent is installed.
Joining a fabric as an non-managed container
osgi:install
, features:install
, and hot deployment), because a Fabric Agent does not take control of its configuration. The agent only registers the container with the fabric's ensemble and keeps the registry entries for it up to date. This enables the newly joined container to discover services running in the container (through Fabric's discovery mechanisms) and to administer these services.
How to join a fabric
- Get the registry service URL for one of the Fabric Servers in the existing fabric. The registry service URL has the following format:
Hostname[:IPPort]
Normally, it is sufficient to specify just the hostname, Hostname, because the registry service uses the fixed port number, 2182, by default. In exceptional cases, you can discover the registry service port by following the instructions in the section called “How to discover the URL of a Fabric Server”. - Get the ZooKeeper password for the fabric. An administrator can access the fabric's ZooKeeper password at any time, by entering the following console command (while logged into one of the Fabric Containers):
JBossFuse:karaf@root> fabric:ensemble-password
- Connect to the standalone container's command console.
- Join a container in one of the following ways:
- Join as a managed container, with a default profile—uses the
fabric
profile.JBossFuse:karaf@root> fabric:join --zookeeper-password ZooPass URL ContainerName
- Join as a managed container, specifying a custom profile—uses a custom profile.
JBossFuse:karaf@root> fabric:join --zookeeper-password ZooPass -p Profile URL ContainerName
- Join as a non-managed container—preserves the existing container configuration.
JBossFuse:karaf@root> fabric:join -n --zookeeper-password ZooPass URL ContainerName
Where you can specify the following values:-
ZooPass
- The existing fabric's ZooKeeper password.
-
URL
- The URL for one of the fabric's registry services (usually just the hostname where a Fabric Server is running).
-
ContainerName
- The new name of the container when it registers itself with the fabric.WarningIf the container your're adding to the fabric has the same name as a container already registered with the fabric, both containers will be reset and will always share the same configuration.
-
Profile
- The name of the custom profile to install into the container after it joins the fabric (managed container only).
- If you joined the container as a managed container, you can subsequently deploy a different profile into the container using the
fabric:container-change-profile
console command.
How to discover the URL of a Fabric Server
- Connect to the command console of one of the containers in the fabric.
- Enter the following sequence of console commands:
JBossA-MQ:karaf@root>
config:edit io.fabric8.zookeeper
JBossA-MQ:karaf@root>
config:proplist
service.pid = io.fabric8.zookeeper zookeeper.url = myhostA:2181,myhostB:2181,myhostC:2181,myhostC:2182,myhostC:2183 fabric.zookeeper.pid = io.fabric8.zookeeperJBossA-MQ:karaf@root>
config:cancel
Thezookeeper.url
property holds a comma-separated list of Fabric Server URLs. You can use any one of these URLs to join the fabric.
Chapter 7. Shutting Down a Fabric
Overview
Shutting down a managed container
fabric:container-stop
command and specify the name of the managed container, for example:
fabric:container-stop -f ManagedContainerName
-f
flag is required when shutting down a container that belongs to the ensemble.
fabric:container-stop
command looks up the container name in the registry and retrieves the data it needs to shut down that container. This approach works no matter where the container is deployed: whether locally or on a remote host.
Shutting down a Fabric Server
registry1
, registry2
, and registry3
. You can shut down only one of these Fabric Servers at a time by using the fabric:container-stop
command, for example:
fabric:container-stop -f registry3
fabric:container-start registry3
Shutting down an entire fabric
fabric:ensemble-remove
and fabric:ensemble-add
commands. Each time you execute one of these commands, it creates a new ensemble. This new ensemble URL is propagated to all containers in the fabric and all containers need to reconnect to the new ensemble. There is a risk for TCP port numbers to be reallocated, which means that your network configuration might become out-of-date because services might start up on different ports.
- Three Fabric Servers (ensemble servers):
registry1
,registry2
,registry3
. - Four managed containers:
managed1
,managed2
,managed3
,managed4
.
- Use the
client
console utility to log on to one of the Fabric Servers in the ensemble. For example, to log on to theregistry1
server, enter a command in the following format:./client -u AdminUser -p AdminPass -h Registry1Host
ReplaceAdminUser
andAdminPass
with the credentials of a user with administration privileges. ReplaceRegistry1Host
with name of the host whereregistry1
is running. It is assumed that theregistry1
server is listening for console connections on the default TCP port (that is,8101
) - Ensure that all managed containers in the fabric are running. Execution of
fabric:container-list
should displaytrue
in thealive
column for each container. This is required for execution of thefabric:ensemble-remove
command, which is the next step. - Remove all but one of the Fabric Servers from the ensemble. For example, if you logged on to
registry1
, enter:fabric:ensemble-remove registry2 registry3
- Shut down all managed containers in the fabric, except the container on the Fabric Server you are logged into. In the following example, the first command shuts down
managed1
,managed2
,managed3
andmanaged4
:fabric:container-stop -f managed* fabric:container-stop -f registry2 fabric:container-stop -f registry3
- Shut down the last container that is still running. This is the container that is on the Fabric Server you are logged in to. For example:
shutdown -f
- Use the
client
console utility to log in to theregistry1
container host. - Start all containers in the fabric.
- Add the other Fabric Servers, for example:
fabric:ensemble-add registry2 registry3
Note on shutting down a complete fabric
fabric:container-stop -f registry1 fabric:container-stop -f registry2 fabric:container-stop -f registry3
fabric:container-stop
fails and throws an error because only one Fabric Server is still running. At least two Fabric Servers must be running to stop a container. With only one Fabric Server running, the registry shuts down and refuses service requests because a quorum of Fabric Servers is no longer available. The fabric:container-stop
command needs the registry to be running so it can retrieve details about the container it is trying to shut down.
Chapter 8. Using Remote Connections to Manage a Container
Abstract
8.1. Configuring a Container for Remote Access
Overview
Configuring a standalone container for remote access
InstallDir/etc/org.apache.karaf.shell.cfg
configuration file. Example 8.1, “Changing the Port for Remote Access” shows a sample configuration that changes the port used to 8102.
Example 8.1. Changing the Port for Remote Access
sshPort=8102 sshHost=0.0.0.0
Configuring a fabric container for remote access
8.2. Connecting and Disconnecting Remotely
Abstract
8.2.1. Connecting to a Standalone Container from a Remote Container
Overview
Using the ssh:ssh console command
Example 8.2. ssh:ssh Command Syntax
ssh:ssh
{
-l username
} {
-P password
} {
-p port
} {
hostname
}
-
-l username
- The username used to connect to the remote container. Use valid JAAS login credentials that have
admin
privileges (see Chapter 14, 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 the section called “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 the section called “Configuring a standalone container for remote access” for details on changing the hostname.
etc/users.properties
file. See Chapter 14, Configuring JAAS Securityfor details.
Example 8.3. Connecting to a Remote Console
JBossFuse:karaf@root>ssh:ssh -l smx -P smx -p 8108 hostname
shell:info
at the prompt. Information about the currently connected instance is returned, as shown in Example 8.4, “Output of the shell:info Command”.
Example 8.4. Output of the shell:info Command
Karaf Karaf version 2.4.0.redhat-630187 Karaf home /home/jboss-fuse-6.3.0.redhat-187 Karaf base /home/jboss-fuse-6.3.0.redhat-187 OSGi Framework org.apache.felix.framework - 4.4.1 JVM Java Virtual Machine Java HotSpot(TM) Server VM version 25.121-b13 Version 1.8.0_121 Vendor Oracle Corporation Pid 4647 Uptime 32.558 seconds Total compile time 45.154 seconds Threads Live threads 87 Daemon threads 69 Peak 88 Total started 113 Memory Current heap size 206,941 kbytes Maximum heap size 932,096 kbytes Committed heap size 655,360 kbytes Pending objects 0 Garbage collector Name = 'PS Scavenge', Collections = 13, Time = 0.343 seconds Garbage collector Name = 'PS MarkSweep', Collections = 2, Time = 0.272 seconds Classes Current classes loaded 10,152 Total classes loaded 10,152 Total classes unloaded 0 Operating system Name Linux version 4.8.14-100.fc23.x86_64 Architecture i386 Processors 4
Disconnecting from a remote console
logout
or press Ctrl+D at the prompt.
8.2.2. Connecting to a Fabric Container From another Fabric Container
Overview
Using the fabric:container-connect command
Example 8.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.
Example 8.6. Connecting to a Remote Container
JBossFuse:karaf@root>fabric:container-connect -u admin -p admin containerName
shell:info
at the prompt. Information about the currently connected instance is returned, as shown in Example 8.7, “Output of the shell:info Command”.
Example 8.7. Output of the shell:info Command
Karaf Karaf version 2.4.0.redhat-630187 Karaf home /home/aaki/Downloads/jboss-fuse-6.3.0.redhat-187 Karaf base /home/aaki/Downloads/jboss-fuse-6.3.0.redhat-187 OSGi Framework org.apache.felix.framework - 4.4.1 JVM Java Virtual Machine Java HotSpot(TM) Server VM version 25.121-b13 Version 1.8.0_121 Vendor Oracle Corporation Pid 4647 Uptime 32.558 seconds Total compile time 45.154 seconds Threads Live threads 87 Daemon threads 69 Peak 88 Total started 113 Memory Current heap size 206,941 kbytes Maximum heap size 932,096 kbytes Committed heap size 655,360 kbytes Pending objects 0 Garbage collector Name = 'PS Scavenge', Collections = 13, Time = 0.343 seconds Garbage collector Name = 'PS MarkSweep', Collections = 2, Time = 0.272 seconds Classes Current classes loaded 10,152 Total classes loaded 10,152 Total classes unloaded 0 Operating system Name Linux version 4.8.14-100.fc23.x86_64 Architecture i386 Processors 4
Disconnecting from a remote console
logout
or press Ctrl+D at the prompt.
8.2.3. Connecting to a Container Using the Client Command-Line Utility
Using the remote client
InstallDir/bin
directory), as follows:
client
client -a 8101 -h hostname -u username -p password shell:info
-p
option, you will be prompted to enter a password.
admin
privileges.
admin
and admin
.
client --help
Example 8.8. Karaf Client Help
Apache 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 (optional, if not provided, the password is prompted) NB: this option is deprecated and will be removed in next Karaf version --help shows this help message -v raise verbosity -l set client logging level. Set to 0 for ERROR logging and up to 4 for TRACE. -r [attempts] retry connection establishment (up to attempts times) -d [delay] intra-retry delay (defaults to 2 seconds) -b batch mode, specify multiple commands via standard input -f [file] read commands from the specified file -k [keyFile] specify the private keyFile location when using key login [commands] commands to run If no commands are specified, the client will be put in an interactive mode
Remote client default credentials
bin/client
, without supplying any credentials. This is because the remote client program is pre-configured to use default credentials. If no credentials are specified, the remote client automatically tries to use the following default credentials (in sequence):
- Default SSH key—tries to login using the default Apache Karaf SSH key. The corresponding configuration entry that would allow this login to succeed is commented out by default in the
etc/keys.properties
file. - Red Hat Fuse does not use
admin
/admin
as the remote default credential. When you log into the application, Fuse would try to useusername
/password
of an item randomly chosen from theetc/users.properties
file. However, it is recommended not to usebin/client
script without-u
option, when you need to useusername
/password
.
admin
/admin
credentials in users.properties
, you will find that the bin/client
utility can log in without supplying credentials.
bin/client
without supplying credentials, this shows that your container is insecure and you must take steps to fix this in a production environment.
Disconnecting from a remote client console
8.2.4. Connecting to a Container Using the SSH Command-Line Utility
Overview
ssh
command-line utility (a standard utility on UNIX-like operating systems) to log in to the Red Hat JBoss Fuse container, where the authentication mechanism is based on public key encryption (the public key must first be installed in the container). For example, given that the container is configured to listen on TCP port 8101, you could log in as follows:
ssh -p 8101 jdoe@localhost
Prerequisites
- The container must be standalone (Fabric is not supported) with the
PublickeyLoginModule
installed. - You must have created an SSH key pair (see the section called “Creating a new SSH key pair”).
- You must install the public key from the SSH key pair into the container (see the section called “Installing the SSH public key in the container”).
Default key location
ssh
command automatically looks for the private key in the default key location. It is recommended that you install your key in the default location, because it saves you the trouble of specifying the location explicitly.
~/.ssh/id_rsa ~/.ssh/id_rsa.pub
C:\Documents and Settings\Username\.ssh\id_rsa C:\Documents and Settings\Username\.ssh\id_rsa.pub
Creating a new SSH key pair
ssh-keygen
utility. Open a new command prompt and enter the following command:
ssh-keygen -t rsa -b 2048
Generating public/private rsa key pair. Enter file in which to save the key (/Users/Username/.ssh/id_rsa):
Enter passphrase (empty for no passphrase):
Installing the SSH public key in the container
InstallDir/etc/keys.properties
file. Each user entry in this file appears on a single line, in the following format:
Username=PublicKey,Role1,Role2,...
~/.ssh/id_rsa.pub
, has the following contents:
ssh-rsa AAAAB3NzaC1kc3MAAACBAP1/U4EddRIpUt9KnC7s5Of2EbdSPO9EAMMeP4C2USZpRV1AIlH7WT2NWPq/xfW6MPbLm1Vs14E7 gB00b/JmYLdrmVClpJ+f6AR7ECLCT7up1/63xhv4O1fnfqimFQ8E+4P208UewwI1VBNaFpEy9nXzrith1yrv8iIDGZ3RSAHHAAAAFQCX YFCPFSMLzLKSuYKi64QL8Fgc9QAAAnEA9+GghdabPd7LvKtcNrhXuXmUr7v6OuqC+VdMCz0HgmdRWVeOutRZT+ZxBxCBgLRJFnEj6Ewo FhO3zwkyjMim4TwWeotifI0o4KOuHiuzpnWRbqN/C/ohNWLx+2J6ASQ7zKTxvqhRkImog9/hWuWfBpKLZl6Ae1UlZAFMO/7PSSoAAACB AKKSU2PFl/qOLxIwmBZPPIcJshVe7bVUpFvyl3BbJDow8rXfskl8wO63OzP/qLmcJM0+JbcRU/53Jj7uyk31drV2qxhIOsLDC9dGCWj4 7Y7TyhPdXh/0dthTRBy6bqGtRPxGa7gJov1xm/UuYYXPIUR/3x9MAZvZ5xvE0kYXO+rx jdoe@doemachine.local
jdoe
user with the admin
role by adding the following entry to the InstallDir/etc/keys.properties
file (on a single line):
jdoe=AAAAB3NzaC1kc3MAAACBAP1/U4EddRIpUt9KnC7s5Of2EbdSPO9EAMMeP4C2USZpRV1AIlH7WT2NWPq/xfW6MPbLm1Vs14E7 gB00b/JmYLdrmVClpJ+f6AR7ECLCT7up1/63xhv4O1fnfqimFQ8E+4P208UewwI1VBNaFpEy9nXzrith1yrv8iIDGZ3RSAHHAAAAFQCX YFCPFSMLzLKSuYKi64QL8Fgc9QAAAnEA9+GghdabPd7LvKtcNrhXuXmUr7v6OuqC+VdMCz0HgmdRWVeOutRZT+ZxBxCBgLRJFnEj6Ewo FhO3zwkyjMim4TwWeotifI0o4KOuHiuzpnWRbqN/C/ohNWLx+2J6ASQ7zKTxvqhRkImog9/hWuWfBpKLZl6Ae1UlZAFMO/7PSSoAAACB AKKSU2PFl/qOLxIwmBZPPIcJshVe7bVUpFvyl3BbJDow8rXfskl8wO63OzP/qLmcJM0+JbcRU/53Jj7uyk31drV2qxhIOsLDC9dGCWj4 7Y7TyhPdXh/0dthTRBy6bqGtRPxGa7gJov1xm/UuYYXPIUR/3x9MAZvZ5xvE0kYXO+rx,admin
id_rsa.pub
file here. Insert just the block of symbols which represents the public key itself.
Checking that public key authentication is supported
jaas:realms
console command, as follows:
Index Realm Module Class 1 karaf org.apache.karaf.jaas.modules.properties.PropertiesLoginModule 2 karaf org.apache.karaf.jaas.modules.publickey.PublickeyLoginModule
PublickeyLoginModule
is installed. With this configuration you can log in to the container using either username/password credentials or public key credentials.
Logging in using key-based SSH
$ ssh -p 8101 jdoe@localhost _ ____ ______ | | _ \ | ____| | | |_) | ___ ___ ___ | |__ _ _ ___ ___ _ | | _ / _ \/ __/ __| | __| | | / __|/ _ \ | |__| | |_) | (_) \__ \__ \ | | | |_| \__ \ __/ \____/|____/ \___/|___/___/ |_| \__,_|___/\___| JBoss Fuse (6.3.0.redhat-xxx) http://www.redhat.com/products/jbossenterprisemiddleware/fuse/ 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 JBoss Fuse. JBossFuse:karaf@root>
ssh
utility will prompt you to enter the pass phrase.
8.3. Stopping a Remote Container
Using the remote console
Using the fabric:container-stop console command
child1
, you would enter the following console command:
JBossFuse:karaf@root>
fabric:container-stop child1
Chapter 9. Managing Child Containers
Abstract
9.1. Standalone Child Containers
Using the admin console commands
Installing the admin console commands
admin
commands are not installed by default. To install the command set, install the admin
feature with the following command:
JBossFuse:karaf@root> features:install admin
Cloning a container
-s
option. For example, to create a new child with the SSH port number of 8102:
JBossFuse:karaf@root> admin:clone -s 8102 root cloned
Creating a Karaf child container
admin:create
command creates a new Apache Karaf child container. That is, the new child container is not a full JBoss Fuse container, and is missing many of the standard bundles, features, and feature repositories that are normally available in a JBoss Fuse container. What you get is effectively a plain Apache Karaf container with JBoss Fuse branding. Additional feature repositories or features that you require will have to be added to the child manually.
instances/containerName
directory. The child container is assigned an SSH port number based on an incremental count starting at 8101.
Example 9.1. Creating a Runtime Instance
JBossFuse:karaf@root> admin:create finn Creating new instance on SSH port 8102 and RMI ports 1100/44445 at: /home/jdoe/apps/fuse/jboss-fuse-6.3.0.redhat-xxx/instances/finn
Changing a child's SSH port
admin:change-port
{
containerName
} {
portNumber
}
Starting child containers
Listing all child containers
Example 9.2. Listing Instances
JBossFuse:karaf@root> admin:list Port State Pid Name [ 8107] [Started ] [10628] harry [ 8101] [Started ] [20076] root [ 8106] [Started ] [15924] dick [ 8105] [Started ] [18224] tom
Connecting to a child container
Example 9.3. Admin connect Command
admin:connect
{
containerName
} {
-u username
} {
-p password
}
- 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 Chapter 14, Configuring JAAS Security).
-
-p
password - This argument specifies the password used to connect to the child's remote console.
JBossFuse:karaf@harry>
Stopping a child container
osgi:shutdown
or simply shutdown
.
admin:stop containerName
.
Destroying a child container
Changing the JVM options on a child container
admin:change-opts
command. For example, you could change the amount of memory allocated to the child container's JVM, as follows:
JBossFuse:karaf@harry> admin:change-opts tom "-server -Xms128M -Xmx1345m -Dcom.sun.management.jmxremote"
Using the admin script
InstallDir/bin
directory provides all of the admin console commands except for admin:connect.
Example 9.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.
admin.bat list
./admin list
9.2. Fabric Child Containers
Creating child containers
fabric:container-create-child
console command, which has the following syntax:
karaf@root> fabric:container-create-child parent child [number]
child1
, child2
, and so on.
karaf@root> fabric:container-create-child root child 2 The following containers have been created successfully: child1 child2
Listing all container instances
fabric:container-list
console command. For example:
JBossFuse:karaf@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
Assigning a profile to a child container
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.
default
to a newly created container by using the fabric:container-create-child command's --profile
argument.
example-camel
profile to the child1
container, enter the following console command:
JBossFuse:karaf@root> fabric:container-change-profile child1 example-camel
child1
and replaces them with the specified list of profiles (where in this case, there is just one profile in the list, example-camel
).
Connecting to a child container
fabric:container-connect
console command. For example, to connect to child1
, enter the following console command:
JBossFuse:karaf@root>
fabric:container-connect -u admin -p admin child1
Connecting to host YourHost on port 8102 Connected _ ____ ______ | | _ \ | ____| | | |_) | ___ ___ ___ | |__ _ _ ___ ___ _ | | _ < / _ \/ __/ __| | __| | | / __|/ _ \ | |__| | |_) | (_) \__ \__ \ | | | |_| \__ \ __/ \____/|____/ \___/|___/___/ |_| \__,_|___/\___| JBoss Fuse (6.0.0.redhat-xxx) http://www.redhat.com/products/jbossenterprisemiddleware/fuse/ 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 JBoss Fuse. JBossFuse:admin@child1>
Ctrl-D
.
Starting a child container
child1
:
JBossFuse:karaf@root>
fabric:container-start child1
Stopping a child container
child1
:
JBossFuse:karaf@root>
fabric:container-stop child1
child1
container.
Destroying a child container
child1
container instance, enter the following console command:
JBossFuse:karaf@root> fabric:container-delete child1
- stops the child's JVM process
- physically removes all files related to the child container
Chapter 10. Deploying a New Broker Instance
Abstract
Overview
Standalone containers
- Create a template Apache ActiveMQ XML configuration file in a location that is accessible to the container.
- In the JBoss Fuse command console, use the config:edit command to create a new OSGi configuration file.ImportantThe PID must start with
io.fabric8.mq.fabric.server-
. - Use the config:propset command to associate your template XML configuration with the broker OSGi configuration as shown in Example 10.1, “Specifying a Broker's Template XML Configuration”.
Example 10.1. Specifying a Broker's Template XML Configuration
JBossFuse:karaf@root>
config:propset config configFile
- Use the config:propset command to set the required properties.The properties that need to be set will depend on the properties you specified using property place holders in the template XML configuration and the broker's network settings.For information on using config:propset see section "config:propset, propset" in "Console Reference".
- Save the new OSGi configuration using the config:update command.
${karaf.base}/etc/broker.xml
. You will also need to provide values for the data property, the broker-name property, and the openwire-port property.
Example
myBroker
that stores its data in InstallDir/data/myBroker
and opens a port at 61617, you would do the following:
- Open the JBoss Fuse command console.
- In the JBoss Fuse command console, use the config:edit command to create a new OSGi configuration file:
JBossFuse:karaf@root>
config:edit io.fabric8.mq.fabric.server-myBroker
- Use the config:propset command to associate your template XML configuration with the broker OSGi configuration:
JBossFuse:karaf@root>
config:propset config ${karaf.base}/etc/broker.xml
- Use the config:propset command to specify the new broker's data directory:
JBossFuse:karaf@root>
config:propset data ${karaf.data}/myBroker
- Use the config:propset command to specify the new broker's name:
JBossFuse:karaf@root>
config:propset broker-name myBroker
- Use the config:propset command to specify the new broker's openwire port:
JBossFuse:karaf@root>
config:propset openwire-port 61617
- Save the new OSGi configuration using the config:update command.
Chapter 11. Configuring JBoss Fuse
Abstract
11.1. Introducing JBoss Fuse Configuration
OSGi configuration
.cfg
file in the InstallDir/etc
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.
Configuration files
Table 11.1. JBoss Fuse Configuration Files
Filename | Description |
---|---|
broker.xml | Configures the default Apache ActiveMQ broker in a Fabric (used in combination with the io.fabric8.mq.fabric.server-default.cfg file). |
config.properties | The main configuration file for the container See Section 11.2, “Setting OSGi Framework and Initial Container Properties” for details. |
keys.properties | Lists the users who can access the JBoss Fuse runtime using the SSH key-based protocol. The file's contents take the format username=publicKey,role |
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 JBoss Fuse 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 Section 16.2, “Logging Configuration”. |
org.apache.karaf.management.cfg |
Configures the JMX system. See Chapter 13, Configuring JMX for details.
|
org.apache.karaf.shell.cfg |
Configures the properties of remote consoles. For more information see Section 8.1, “Configuring a Container for Remote Access”.
|
io.fabric8.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.) |
io.fabric8.mq.fabric.server-default.cfg | Configures the default Apache ActiveMQ broker in a Fabric (used in combination with the broker.xml file). |
org.ops4j.pax.logging.cfg |
Configures the logging system. For more, see Section 16.2, “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. |
startup.properties
| 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
System.getProperties() . See Setting System and Config Properties for more.
|
users.properties | Lists the users who can access the JBoss Fuse runtime either remotely or via the web console. The file's contents take the format username=password,role |
setenv or setenv.bat | This file is in the /bin directory. It is used to set JVM options. The file's contents take the format JAVA_MIN_MEM=512M, where 512M is the minimum size of Java memory. See Setting Java Options for more information. |
Configuration file naming convention
<PID>.cfg
<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
.
<PID>-<InstanceID>.cfg
<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.
Setting Java Options
/bin/setenv
file in Linux, or the bin/setenv.bat
file for Windows. Use this file to directly set a group of Java options: JAVA_MIN_MEM, JAVA_MAX_MEM, JAVA_PERM_MEM, JAVA_MAX_PERM_MEM. Other Java options can be set using the EXTRA_JAVA_OPTS variable.
JAVA_MIN_MEM=512M # Minimum memory for the JVMTo set a Java option other than the direct options, use
EXTRA_JAVA_OPTS="Java option"For example,
EXTRA_JAVA_OPTS="-XX:+UseG1GC"
11.2. Setting OSGi Framework and Initial Container Properties
Overview
etc
folder:
config.properties
—specifies the bootstrap properties for the OSGi frameworksystem.properties
—specifies properties to configure container functions
OSGi framework properties
etc/config.properties
file contains the properties used to specify which OSGi framework implementation to load and properties for configuring the framework's behaviors. Table 11.2, “Properties for the OSGi Framework” describes the key properties to set.
Table 11.2. Properties for the OSGi Framework
Property | Description |
---|---|
karaf.framework | Specifies the OSGi framework that Red Hat JBoss Fuse uses. The default framework is Apache Felix which is specified using the value felix . |
karaf.framework.felix | Specifies the path to the Apache Felix JAR on the file system. |
Initial container properties
etc/system.properties
file contains properties that configure how various aspects of the container behave including:
- the container's name
- the default feature repository used by the container
- the default port used by the OSGi HTTP service
- the initial message broker configuration
Table 11.3. Container Properties
Property | Description |
---|---|
karaf.name | Specifies the name of this container. The default is root . |
karaf.default.repository | Specifies the location of the feature repository the container will use by default. The default setting is the local feature repository installed with JBoss Fuse. |
org.osgi.service.http.port | Specifies the default port for the OSGi HTTP Service. |
11.3. Configuring Standalone Containers Using the Command Console
Overview
Listing the current configuration
Example 11.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 = /home/apache/jboss-fuse-6.3.0.redhat-xxx/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 ---------------------------------------------------------------- ...
Editing the 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
.
config:cancel
.
Example 11.2. Editing a Configuration
JBossFuse:karaf@root>
config:edit org.apache.karaf.log
JBossFuse:karaf@root>
config:proplist
service.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%n
JBossFuse:karaf@root>
config:propset size 300
JBossFuse:karaf@root>
config:update
11.4. Configuring Fabric Containers
Overview
Profiles
- 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
Best practices
Making changes using the command console
- 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 11.3. Editing Fabric Profile
JBossFuse:karaf@root>
fabric:version-create
Created version: 1.1 as copy of: 1.0
JBossFuse:karaf@root>
fabric:profile-edit -p org.apache.karaf.log/size=300 NEBroker
Using the management console
Chapter 12. Configuring the Hot Deployment System
Abstract
Overview
org.apache.felix.fileinstall-deploy
PID.
Specifying the hot deployment folder
deploy
folder that is relative to the folder from which you launched the container. You change the folder the container monitors by setting the felix.fileinstall.dir property in the rg.apache.felix.fileinstall-deploy
PID. The value is the absolute path of the folder to monitor. If you set the value to /home/joe/deploy
, the container will monitor a folder in Joe's home directory.
Specifying the scan interval
org.apache.felix.fileinstall-deploy
PID. The value is specified in milliseconds.
Example
/home/karaf/hot
as the hot deployment folder and sets the scan interval to half a second.
Example 12.1. Configuring the Hot Deployment Folders
JBossFuse:karaf@root>
config:edit org.apache.felix.fileinstall-deploy
JBossFuse:karaf@root>
config:propset felix.fileinstall.dir /home/karaf/hot
JBossFuse:karaf@root>
config:propset felix.fileinstall.poll 500
JBossFuse:karaf@root>
config:update
Chapter 13. Configuring JMX
Abstract
Overview
org.apache.karaf.management
PID.
Changing the RMI port and JMX URL
Table 13.1. JMX Access Properties
Property | Description |
---|---|
rmiRegistryPort | Specifies the RMI registry port. The default value is 1099. |
serviceUrl | Specifies the the URL used to connect to the JMX server. The default URL is service:jmx:rmi://${rmiServerHost}:${rmiServerPort}/jndi/rmi://${rmiRegistryHost}:${rmiRegistryPort}/karaf-${karaf.name}, where karaf.name is the container's name (by default, root ). All ${...} placeholders are replaced by properties with the same names as they are inside parentheses |
Setting the JMX username and password
admin
and the default password is admin
.
Restricting JMX to Accept Only Local Connections
service:jmx:rmi://127.0.0.1:44444/jndi/rmi://127.0.0.1:1099/karaf-root
- The RMI registry tells JMX clients where to find the JMX RMI server port; information can be obtained under key jmxrmi.
- The RMI registry port is generally known as it is set through the system properties at JVM startup. The default value is 1099.
- The JMX RMI server port is generally not known as the JVM chooses it at random.
- Change the iptables to add a redirecting rule. When you call on 44444 port, it redirects all the network interfaces to IP 127.0.0.1:44444.
sudo iptables -t nat -I OUTPUT -p tcp -o lo --dport 44444 -j REDIRECT --to-ports 44444
- Before starting the container, set the system property java.rmi.server.hostname to 127.0.0.1 port. It works even without iptables re-directing the rule in place.
export JAVA_OPTS="-Djava.rmi.server.hostname=127.0.0.1" bin/fuse
etc/org.apache.karaf.management.cfg
configuration file.
Troubleshooting on Linux platforms
- Check that the hostname resolves to the correct IP address. For example, if the
hostname -i
command returns 127.0.0.1, JConsole will not be able to connect to the JMX server. To fix this, edit the/etc/hosts
file so that the hostname resolves to the correct IP address. - Check whether the Linux machine is configured to accept packets from the host where JConsole is running (packet filtering is built in the Linux kernel). You can enter the command,
/sbin/iptables --list
, to determine whether an external client is allowed to connect to the JMX server.Use the following command to add a rule to allow an external client such as JConsole to connect:/usr/sbin/iptables -I INPUT -s JconsoleHost -p tcp --destination-port JMXRemotePort -j ACCEPT
Where JconsoleHost is either the hostname or the IP address of the host on which JConsole is running and JMXRemotePort is the TCP port exposed by the JMX server.
Chapter 14. Configuring JAAS Security
14.1. Alternative JAAS Realms
Overview
Default realm
karaf
realm name. The standard administration services in JBoss Fuse (SSH remote console, JMX port, and so on) are all configured to use the karaf
realm by default.
Available realm implementations
Standalone JAAS realm
karaf
realm installs four JAAS login modules, which are used in parallel:
PropertiesLoginModule
- Authenticates username/password credentials and stores the secure user data in the
InstallDir/etc/users.properties
file. PublickeyLoginModule
- Authenticates SSH key-based credentials (consisting of a username and a public/private key pair). Secure user data is stored in the
InstallDir/etc/keys.properties
file. FileAuditLoginModule
- Provides an audit trail of successful/failed login attempts, which are logged to an audit file. Does not perform user authentication.
EventAdminAuditLoginModule
- Provides an audit trail of successful/failed login attempts, which are logged to the OSGi Event Admin service. Does not perform user authentication.
Fabric JAAS realm
karaf
realm based on the ZookeeperLoginModule
login module is automatically installed in every container (the fabric-jaas
feature is included in the default profile) and is responsible for securing the SSH remote console and other administrative services. The Zookeeper login module stores the secure user data in the Fabric Registry.
karaf
realm with a higher rank.
LDAP JAAS realm
14.2. JAAS Console Commands
Editing user data from the console
jaas:*
console commands, which you can use to edit JAAS user data from the console. This works both for standalone JAAS realms and for Fabric JAAS realms.
jaas:*
console commands are not compatible with the LDAP JAAS module.
Standalone realm configuration
PropertiesLoginModule
and the PublickeyLoginModule
) maintains its own database of secure user data, independently of any other containers. To configure the user data for a standalone container, you must log into the specific container (see Connecting and Disconnecting Remotely) whose data you want to modify. Each standalone container must be configured separately.
jaas:realms
command, as follows:
JBossFuse:karaf@root> jaas:realms Index Realm Module Class 1 karaf org.apache.karaf.jaas.modules.properties.PropertiesLoginModule 2 karaf org.apache.karaf.jaas.modules.publickey.PublickeyLoginModule 3 karaf org.apache.karaf.jaas.modules.audit.FileAuditLoginModule 4 karaf org.apache.karaf.jaas.modules.audit.EventAdminAuditLoginModule
karaf
JAAS realm. Enter the following console command to start editing the properties login module in the karaf
realm:
JBossFuse:karaf@root> jaas:manage --index 1
Fabric realm configuration
ZookeeperLoginModule
by default) shares its secure user data with all of the other containers in the fabric and the user data is stored in the Fabric Registry. To configure the user data for a fabric, you can log into any of the containers. Because the user data is shared in the registry, any modifications you make are instantly propagated to all of the containers in the fabric.
jaas:realms
console command, you might see a listing similar to this:
Index Realm Module Class 1 karaf io.fabric8.jaas.ZookeeperLoginModule 2 karaf org.apache.karaf.jaas.modules.properties.PropertiesLoginModule 3 karaf org.apache.karaf.jaas.modules.publickey.PublickeyLoginModule
ZookeeperLoginModule
login module has the highest priority and is used by the fabric (you cannot see this from the listing, but its realm is defined to have a higher rank than the other modules). In this example, the ZookeeperLoginModule
has the index 1
, but it might have a different index number in your container.
ZookeeperLoginModule
):
JBossFuse:karaf@root> jaas:manage --index 1
Adding a new user to the JAAS realm
jdoe
, to the JAAS realm.
- List the available realms and login modules by entering the following command:
JBossFuse:karaf@root> jaas:realms
- Choose the login module to edit by specifying its index, Index, using a command of the following form:
JBossFuse:karaf@root> jaas:manage --index Index
jdoe
, with password, secret
, by entering the following console command:
JBossFuse:karaf@root> jaas:useradd jdoe secret
admin
role to jdoe
, by entering the following console command:
JBossFuse:karaf@root> jaas:roleadd jdoe admin
jaas:pending
console command, as follows:
JBossFuse:karaf@root> jaas:pending Jaas Realm:karaf Jaas Module:org.apache.karaf.jaas.modules.properties.PropertiesLoginModule UserAddCommand{username='jdoe', password='secret'} RoleAddCommand{username='jdoe', role='admin'}
jaas:update
, as follows:
JBossFuse:karaf@root> jaas:update
etc/users.properties
file, in the case of a standalone container, or by storing the user data in the Fabric Registry, in the case of a fabric).
\
. For example, jaas:useradd username hello\!world
. Your password will be hello!world
.
Canceling pending changes
jaas:update
command, you could abort the pending changes using the jaas:cancel
command, as follows:
JBossFuse:karaf@root> jaas:cancel
14.3. Standalone Realm Properties File
Overview
PropertiesLoginModule
JAAS module. This login module stores its user data in a Java properties file in the following location:
InstallDir/etc/users.properties
Format of users.properties entries
etc/users.properties
file has the following format (on its own line):
Username=Password[,UserGroup|Role][,UserGroup|Role]...
Changing the default username and password
etc/users.properties
file initially contains a commented out entry for a single user, admin, with password admin and role admin. It is strongly recommended that you create a new user entry that is different from the admin
user example.
Username=Password,Administrator
Administrator
role grants full administration privileges to this user.
Chapter 15. Securing Fabric Containers
Abstract
Default authentication system
io.fabric8.jaas.ZookeeperLoginModule
). This system allows you to define user accounts and assign passwords and roles to the users. Out of the box, the user credentials are stored in the Fabric registry, unencrypted.
Managing users
jaas:*
family of console commands. First of all you need to attach the jaas:*
commands to the ZookeeperLoginModule
login module, as follows:
JBossFuse:karaf@root> jaas:realms Index Realm Module Class 1 karaf org.apache.karaf.jaas.modules.properties.PropertiesLoginModule 2 karaf org.apache.karaf.jaas.modules.publickey.PublickeyLoginModule 3 karaf io.fabric8.jaas.ZookeeperLoginModule JBossFuse:karaf@root> jaas:manage --index 3
jaas:*
commands to the ZookeeperLoginModule
login module. You can then add users and roles, using the jaas:useradd
and jaas:roleadd
commands. Finally, when you are finished editing the user data, you must commit the changes by entering the jaas:update
command, as follows:
JBossFuse:karaf@root> jaas:update
jaas:cancel
.
Obfuscating stored passwords
ZookeeperLoginModule
stores passwords in plain text. You can provide additional protection to passwords by storing them in an obfuscated format. This can be done by adding the appropriate configuration properties to the io.fabric8.jaas
PID and ensuring that they are applied to all of the containers in the fabric.
Enabling LDAP authentication
LDAPLoginModule
), which you can enable by adding the requisite configuration to the default profile.
Chapter 16. Logging
Abstract
16.1. Logging Overview
- Apache Log4j
- Apache Commons Logging
- SLF4J
- Java Util Logging
16.2. Logging Configuration
Overview
etc/system.properties
—the configuration file that sets the logging level during the container’s boot process. The file contains a single property, org.ops4j.pax.logging.DefaultServiceLog.level, that is set toERROR
by default.org.ops4j.pax.logging
—the PID used to configure the logging back end service. It sets the logging levels for all of the defined loggers and defines the appenders used to generate log output. It uses standard Log4j configuration. By default, it sets the root logger's level toINFO
and defines two appenders: one for the console and one for the log file.NoteThe console's appender is disabled by default. To enable it, addlog4j.appender.stdout.append=true
to the configuration For example, to enable the console appender in a standalone container, you would use the following commands:JBossFuse:karaf@root>
config:edit org.ops4j.pax.logging
JBossFuse:karaf@root>
config:propappend log4j.appender.stdout.append true
JBossFuse:karaf@root>
config:update
org.apache.karaf.log.cfg
—configures the output of the log console commands.
Changing the log levels
org.ops4j.pax.logging
PID's log4j.rootLogger
property so that the logging level is one of the following:
TRACE
DEBUG
INFO
WARN
ERROR
FATAL
OFF
Example 16.1. Changing Logging Levels
JBossFuse:karaf@root>
config:edit org.ops4j.pax.logging
JBossFuse:karaf@root>
config:propset log4j.rootLogger "DEBUG, out, osgi:VmLogAppender"
JBossFuse:karaf@root>
config:update
Changing the appenders' thresholds
log4j.appender.appenderName.threshold
property that controls what level of messages are written to the appender. The appender threshold values are the same as the log level values.
DEBUG
but limiting the information displayed on the console to WARN
.
Example 16.2. Changing the Log Information Displayed on the Console
JBossFuse:karaf@root>
config:edit org.ops4j.pax.logging
JBossFuse:karaf@root>
config:propset log4j.rootLogger "DEBUG, out, osgi:VmLogAppender"
JBossFuse:karaf@root>
config:propappend log4j.appender.stdout.threshold WARN
JBossFuse:karaf@root>
config:update
Logging per bundle
sift
appender to the Log4j root logger as shown in Example 16.3, “Enabling Per Bundle Logging”.
Example 16.3. Enabling Per Bundle Logging
JBossFuse:karaf@root>
config:edit org.ops4j.pax.logging
JBossFuse:karaf@root>
config:propset log4j.rootLogger "INFO, out, sift, osgi:VmLogAppender"
JBossFuse:karaf@root>
config:update
data/log/BundleName.log
.
org.ops4j.pax.logging.cfg
.
Logging History
~/.karaf/karaf.history
. JBoss Fuse can be configured to prevent the history from being saved each time.
Procedure 16.1. Stop JBoss Fuse saving Logging History on shutdown.
- Stop JBoss Fuse.
- Edit
$FUSE_HOME/etc/system.properties
. - Uncomment the line that says
# karaf.shell.history.maxSize = 0
. - Restart JBoss Fuse
~/.karaf/karaf.history
will still be created, but it will always have a size of 0, and will be empty.
16.3. Logging per Application
Overview
Application key
Enabling per application logging
- In each of your applications, edit the Java source code to define a unique application key.If you are using slf4j, add the following static method call to your application:
org.slf4j.MDC.put("app.name","MyFooApp");
If you are using log4j, add the following static method call to your application:org.apache.log4j.MDC.put("app.name","MyFooApp");
- Edit the
etc/org.ops4j.pax.logging
PID to customize the sift appender.- Set
log4j.appender.sift.key
toapp.name
. - Set
log4j.appender.sift.appender.file
to=${karaf.data}/log/$\\{app.name\\}.log
.
- Edit the
etc/org.ops4j.pax.logging
PID to add the sift appender to the root logger.JBossFuse:karaf@root>
config:edit org.ops4j.pax.logging
JBossFuse:karaf@root>
config:propset log4j.rootLogger "INFO, out, sift, osgi:VmLogAppender"
JBossFuse:karaf@root>
config:update
16.4. Log Commands
- log:display
- Displays the most recent log entries. By default, the number of entries returned and the pattern of the output depends on the size and pattern properties in the
org.apache.karaf.log.cfg
file. You can override these using the-p
and-d
arguments. - log:display-exception
- Displays the most recently logged exception.
- log:get
- Displays the current log level.
- log:set
- Sets the log level.
- log:tail
- Continuously display log entries .
- log:clear
- Clear log entries.
Chapter 17. Persistence
Abstract
Overview
data
folder in the directory from which you launch the container. This folder is populated by folders storing information about the message broker used by the container, the OSGi framework, and the Karaf container.
The data folder
data
folder is used by the JBoss Fuse runtime to store persistent state information. It contains the following folders:
amq
- Contains persistent data needed by any Apache ActiveMQ brokers that are started by the container.
cache
- The OSGi bundle cache. The cache contains a directory for each bundle, where the directory name corresponds to the bundle identifier number.
generated-bundles
- Contains bundles that are generated by the container.
log
- Contains the log files.
maven
- A temporary directory used by the Fabric Maven Proxy when uploading files.
txlog
- Contains the log files used by the transaction management system. You can set the location of this directory in the
org.apache.aries.transaction.cfg
file
Changing the bundle cache location
InstallDir/data/cache
.
config.properties
.
Flushing the bundle cache
config.properties
. This property is set to none by default.
Changing the generated-bundle cache location
org.apache.felix.fileinstall-deploy.cfg
file.
Adjusting the bundle cache buffer
config.properties
configuration file. The value is specified in bytes.
Chapter 18. Failover Deployments
Abstract
18.1. Using a Simple Lock File System
Overview
Configuring a lock file system
etc/system.properties
file on both the master and the slave installation to include the properties in Example 18.1, “Lock File Failover Configuration”.
Example 18.1. Lock File Failover Configuration
karaf.lock=true karaf.lock.class=org.apache.karaf.main.SimpleFileLock karaf.lock.dir=PathToLockFileDirectory karaf.lock.delay=10000
- karaf.lock—specifies whether the lock file is written.
- karaf.lock.class—specifies the Java class implementing the lock. For a simple file lock it should always be
org.apache.karaf.main.SimpleFileLock
. - karaf.lock.dir—specifies the directory into which the lock file is written. This must be the same for both the master and the slave installation.
- karaf.lock.delay—specifies, in milliseconds, the delay between attempts to reaquire the lock.
18.2. Using a JDBC Lock System
Overview
Adding the JDBC driver to the classpath
- Copy the JDBC driver JAR file to the
ESBInstallDir/lib
directory for each Red Hat JBoss Fuse instance. - Modify the
bin/karaf
start script so that it includes the JDBC driver JAR in itsCLASSPATH
variable.For example, given the JDBC JAR file,JDBCJarFile.jar
, you could modify the start script as follows (on a *NIX operating system):... # Add the jars in the lib dir for file in "$KARAF_HOME"/lib/karaf*.jar do if [ -z "$CLASSPATH" ]; then CLASSPATH="$file" else CLASSPATH="$CLASSPATH:$file" fi done CLASSPATH="$CLASSPATH:$KARAF_HOME/lib/JDBCJarFile.jar"
NoteIf you are adding a MySQL driver JAR or a PostgreSQL driver JAR, you must rename the driver JAR by prefixing it with thekaraf-
prefix. Otherwise, Apache Karaf will hang and the log will tell you that Apache Karaf was unable to find the driver.
Configuring a JDBC lock system
etc/system.properties
file for each instance in the master/slave deployment as shown
Example 18.2. JDBC Lock File Configuration
karaf.lock=true karaf.lock.class=org.apache.karaf.main.DefaultJDBCLock karaf.lock.level=50 karaf.lock.delay=10000 karaf.lock.jdbc.url=jdbc:derby://dbserver:1527/sample karaf.lock.jdbc.driver=org.apache.derby.jdbc.ClientDriver karaf.lock.jdbc.user=user karaf.lock.jdbc.password=password karaf.lock.jdbc.table=KARAF_LOCK karaf.lock.jdbc.clustername=karaf karaf.lock.jdbc.timeout=30
Configuring JDBC locking on Oracle
etc/system.properties
file must point to org.apache.karaf.main.OracleJDBCLock.
system.properties
file as normal for your setup, as shown:
Example 18.3. JDBC Lock File Configuration for Oracle
karaf.lock=true karaf.lock.class=org.apache.karaf.main.OracleJDBCLock karaf.lock.jdbc.url=jdbc:oracle:thin:@hostname:1521:XE karaf.lock.jdbc.driver=oracle.jdbc.OracleDriver karaf.lock.jdbc.user=user karaf.lock.jdbc.password=password karaf.lock.jdbc.table=KARAF_LOCK karaf.lock.jdbc.clustername=karaf karaf.lock.jdbc.timeout=30
Configuring JDBC locking on Derby
etc/system.properties
file should point to org.apache.karaf.main.DerbyJDBCLock. For example, you could configure the system.properties
file as shown:
Example 18.4. JDBC Lock File Configuration for Derby
karaf.lock=true karaf.lock.class=org.apache.karaf.main.DerbyJDBCLock karaf.lock.jdbc.url=jdbc:derby://127.0.0.1:1527/dbname karaf.lock.jdbc.driver=org.apache.derby.jdbc.ClientDriver karaf.lock.jdbc.user=user karaf.lock.jdbc.password=password karaf.lock.jdbc.table=KARAF_LOCK karaf.lock.jdbc.clustername=karaf karaf.lock.jdbc.timeout=30
Configuring JDBC locking on MySQL
etc/system.properties
file must point to org.apache.karaf.main.MySQLJDBCLock. For example, you could configure the system.properties
file as shown:
Example 18.5. JDBC Lock File Configuration for MySQL
karaf.lock=true karaf.lock.class=org.apache.karaf.main.MySQLJDBCLock karaf.lock.jdbc.url=jdbc:mysql://127.0.0.1:3306/dbname karaf.lock.jdbc.driver=com.mysql.jdbc.Driver karaf.lock.jdbc.user=user karaf.lock.jdbc.password=password karaf.lock.jdbc.table=KARAF_LOCK karaf.lock.jdbc.clustername=karaf karaf.lock.jdbc.timeout=30
Configuring JDBC locking on PostgreSQL
etc/system.properties
file must point to org.apache.karaf.main.PostgreSQLJDBCLock. For example, you could configure the system.properties
file as shown:
Example 18.6. JDBC Lock File Configuration for PostgreSQL
karaf.lock=true karaf.lock.class=org.apache.karaf.main.PostgreSQLJDBCLock karaf.lock.jdbc.url=jdbc:postgresql://127.0.0.1:5432/dbname karaf.lock.jdbc.driver=org.postgresql.Driver karaf.lock.jdbc.user=user karaf.lock.jdbc.password=password karaf.lock.jdbc.table=KARAF_LOCK karaf.lock.jdbc.clustername=karaf karaf.lock.jdbc.timeout=0
JDBC lock classes
org.apache.karaf.main.DefaultJDBCLock org.apache.karaf.main.DerbyJDBCLock org.apache.karaf.main.MySQLJDBCLock org.apache.karaf.main.OracleJDBCLock org.apache.karaf.main.PostgreSQLJDBCLock
18.3. Container-level Locking
Overview
Configuring container-level locking
etc/system.properties
file on each system in the master/slave setup:
Example 18.7. Container-level Locking Configuration
karaf.lock=true karaf.lock.level=50 karaf.lock.delay=10000
etc/startup.properties
, in the format BundleName.jar=level. The core system bundles have levels below 50, where as user bundles have levels greater than 50.
Table 18.1. Bundle Start Levels
Start Level | Behavior |
---|---|
1 | A 'cold' standby instance. Core bundles are not loaded into container. Slaves will wait until lock acquired to start server. |
<50 | A 'hot' standby instance. Core bundles are loaded into the container. Slaves will wait until lock acquired to start user level bundles. The console will be accessible for each slave instance at this level. |
>50 | This setting is not recommended as user bundles will be started. |
Avoiding port conflicts
fuse
start script (or the karaf
script on a child instance) to include the following:
DEFAULT_JAVA_OPTS="-server $DEFAULT_JAVA_OPTS -Dcom.sun.management.jmxremote.port=1100 -Dcom.sun.management.jmxremote.authenticate=false"
Chapter 19. Applying Patches
Abstract
19.1. Patching Overview
- Customer Support sends you a patch.
- Customer Support sends you a link to download a patch.
- Download a patch directly from the Red Hat customer portal.
- Standalone (standard process)—using commands from the Karaf console's patch shell. This approach is non-destructive and reversible.
- Fabric—patching a fabric requires applying the patch to a profile and then applying the profile to a container.
19.2. Finding the Right Patches to Apply
Abstract
Locate the patches on the customer portal
- Login to the Red Hat Customer Portal using your customer account. This account must be associated with an appropriate Red Hat software subscription, otherwise you will not be able to see the patch downloads for JBoss Fuse.
- Navigate to the customer portal Software Downloads page.
- In the Product dropdown menu, select the appropriate product (for example, A-MQ or Fuse), and then select the version, 6.3, from the Version dropdown menu. A table of downloads now appears, which has three tabs: Releases, Patches, and Security Advisories.
- Click the Releases tab to view the GA product releases.
- Click the Patches tab the rollup patches, and the regular incremental patches (with no security-related fixes).
- Click the Security Advisories tab to view the incremental patches with security-related fixes.
Types of patch
- Rollup patches
- Incremental patches
Rollup patches
- Each rollup patch file is a complete new build of the official target distribution. This means you can unzip the rollup patch file to obtain a completely new installation of JBoss Fuse, just as if it was a fresh download of the product (which, in fact, it is). See Section 19.3, “Installing a Rollup Patch as a New Installation”.
- You can also treat the rollup patch as a regular patch, using it to upgrade an existing installation. That is, you can provide the rollup patch file as an argument to the standalone patch console commands (for example,
patch:add
andpatch:install
) or the Fabric patch console command,patch:fabric-install
.
Incremental patches
Which patches are needed to update the GA product to the latest patch level?
- If the only patches released so far are patches with GA baseline (Patch 1, Patch 2, and so on), apply the latest of these patches directly to the GA product.
- If a rollup patch has been released and no patches have been released after the latest rollup patch, simply apply the latest rollup patch to the GA product.
- If the latest patch is a patch with a rollup baseline, you must apply two patches to the GA product, as follows:
- Apply the latest rollup patch, and then
- Apply the latest patch with a rollup baseline.
Which patches to apply, if you only want to install regression-tested patches?
19.3. Installing a Rollup Patch as a New Installation
A rollup patch is a new build
Installing the new build
- Identify which rollup patch you need to install and download it from the Customer Portal. For more details, see Section 19.2, “Finding the Right Patches to Apply”.
- Unzip the rollup patch file to a convenient location, just as you would with a regular GA distribution. This is your new installation of JBoss Fuse.
Comparison with patch process
- This approach is only for creating a completely new installation of JBoss Fuse. If your existing installation already has a lot of custom configuration, this might not be the most convenient approach to use.
- The new build includes only the artifacts and configuration for the new patch level. There is thus no concept of rolling back to the GA version.
- If you create a new fabric (using
fabric:create
), the default fabric profiles are already at the new patch level (same as the standalone container). It is therefore not necessary to patch the fabric.
19.4. Patching a Standalone Container
Abstract
Overview
Incremental patch
- Updates bundle JARs.
- Patches only the current container instance (under the
data/
directory). Hence, patches are not preserved after deleting a container instance. - Updates any feature dependencies installed in the current container instance, but does not update the feature files themselves.
- Might update some configuration files, but is not suitable for updating most configuration files.
- Supports patch rollback.
- After applying the patch, and creating a new fabric using
fabric:create
, the new Fabric reverts to the unpatched configuration.
etc/startup.properties
and etc/overrides.properties
files. With these files, the Karaf installation is able to persist the patch even after deleting the root container instance (that is, after removing the root container's data/
directory).
data/cache
directory uninstalls any bundles, features, or feature repositories that were installed into the container using Karaf console commands. However, any patches that have been applied will remain installed, as long as the etc/startup.properties
and etc/overrides.properties
files are preserved.
Rollup patch
etc/
directory). A rollup patch:
- Updates any files, including bundle JARs, configuration files, and any static files.
- Patches both the current container instance (under the
data/
directory) and the underlying installation. Hence, patches are preserved after deleting a container instance. - Updates all of the files related to Karaf features, including the features repository files and the features themselves. Hence, any features installed after the rollup patch will reference the correct patched dependencies.
- If necessary, updates configuration files (for example, files under
etc/
), automatically merging any configuration changes you have made with the configuration changes made by the patch. If merge conflicts occur, see the patch log for details of how they are handled. - Tracks all of the changes made to the installation (including to static files), so that it is possible to roll back the patch.NoteThe rollup patching mechanism uses an internal git repository (located under
patches/.management/history
) to track the changes made. - After applying the patch, and creating a new fabric using
fabric:create
, the new Fabric is created with the patched configuration.
Patching the patch mechanism
- Download the appropriate patch management package. From the JBoss Fuse 6.3.0 Software Downloads page, select a package named Red Hat JBoss Fuse 6.3.0 Rollup N on Karaf Update Installer, where N is the number of the particular rollup patch you are about to install.ImportantThe rollup number, N, of the downloaded patch management package must match the rollup number of the rollup patch you are about to install. For some rollup patches, there is no corresponding patch management package, in which case you can skip directly to the instructions for installing the rollup patch.
- Install the patch management package,
patch-management-for-fuse-630-TargetVersion.zip
, on top of your 6.3.0 installation. Use an archive utility to extract the contents on top of the existing Karaf container installation (installing files under thesystem/
andpatches/
subdirectories).ImportantEnsure the credentials you are using to unzip the file are the same credentials used to install Fuse; otherwise, an error may occur since Fuse will not have access to the patched file.NoteIt does not matter whether the container is running or not when you extract these files. - Start the container, if it is not already running.
- Uninstall the existing patch commands from the container as follows. Remove the patch features as follows:
JBossFuse:karaf@root> features:uninstall patch patch-core
But this is not sufficient to remove all of the patch bundles. Check for any remaining patch bundles as follows:JBossFuse:karaf@root> list -t 0 -l | grep patch [ 1] [Active ] [ ] [ ] [ 2] mvn:io.fabric8.patch/patch-management/1.2.0.redhat-630xxx
You can remove this system bundle, as follows:JBossFuse:karaf@root> uninstall 1 You are about to access system bundle 1. Do you wish to continue (yes/no): yes JBossFuse:karaf@root> list -t 0 -l | grep patch
Finally, you should remove the features URL for the old patch mechanism version, as follows:JBossFuse:karaf@root> features:listurl | grep patch true mvn:io.fabric8.patch/patch-features/1.2.0.redhat-630xxx/xml/features JBossFuse:karaf@root> features:removeurl mvn:io.fabric8.patch/patch-features/1.2.0.redhat-630xxx/xml/features
Check the version ofpatch-features
that you have, because it might be different from1.2.0.redhat-630xxx
. - Install the new patch commands as follows. Add the features URL for the new patch commands, as follows:
JBossFuse:karaf@root> features:addurl mvn:io.fabric8.patch/patch-features/1.2.0.redhat-630xxx/xml/features
Where you must replace1.2.0.redhat-630xxx
with the actual build version of the patch commands you are installing (for example, the build versionxxx
can be taken from the last three digits of theTargetVersion
in the downloaded patch management package file name).Install the new patch features, as follows:JBossFuse:karaf@root> features:install patch-core patch
Check that the requisite patch bundles are now installed:JBossFuse:karaf@root> list -t 0 -l | grep patch [ 265] [Active ] [ ] [ ] [ 80] mvn:io.fabric8.patch/patch-core/1.2.0.redhat-630xxx [ 266] [Active ] [ ] [ ] [ 2] mvn:io.fabric8.patch/patch-management/1.2.0.redhat-630xxx [ 267] [Active ] [ ] [ ] [ 80] mvn:io.fabric8.patch/patch-commands/1.2.0.redhat-630xxx
- Restart the container (the
patch:add
command and the other patch commands will not be available in the console shell until you perform a restart).
Applying a patch
- Make a full backup of your JBoss Fuse installation before attempting to apply the patch.
- (Rollup patch only) Before applying the rollup patch to your container, you must patch the patch mechanism, as described in the section called “Patching the patch mechanism”.
- (Rollup patch only) Remove the
lib/endorsed/org.apache.karaf.exception-2.4.0.redhat-630xxx.jar
file (where the build number,xxx
, depends on the build being patched). - (Incremental patch only) Before you proceed to install the patch, make sure to read the text of the
README
file that comes with the patch, as there might be additional manual steps required to install a particular patch. - Start the container, if it is not already running. If the container is running in the background (or remotely), connect to the container using the SSH console client,
/bin/client
. - Add the patch to the container's environment by invoking the patch:add command. For example, to add the
patch.zip
patch file:patch:add file://patch.zip
- Simulate installing the patch by invoking the patch:simulate command.This generates a log of the changes that will be made to the container when the patch is installed, but will not make any actual changes to the container. Review the simulation log to understand the changes that will be made to the container.
- Invoke the patch:list command to display a list of added patches. In this list, the entries under the
[name]
heading are patch IDs. For example:patch:list [name] [installed] [description] jboss-a-mq-6.3.0.redhat-329 false
Ensure that the container has fully started before you try to perform the next step. In some cases, the container must restart before you can apply a patch, for example, if static files are patched. In these cases, the container restarts automatically. - Apply a patch to the container by invoking the patch:install command and specifying the patch ID for the patch that you want to apply. For example:
patch:install jboss-a-mq-6.3.0.redhat-329
- Validate the patch, by searching for one of the patched artifacts. For example, if you had just upgraded JBoss Fuse 6.2.1 to the patch with build number
621423
, you could search for bundles with this build number, as follows:JBoss Fuse:karaf@root> osgi:list -s -t 0 | grep -i 630xxx [ 6] [Active ] [ ] [ ] [ 10] org.apache.felix.configadmin (1.2.0.redhat-630xxx)
After applying a rollup patch, you also see the new version and build number in the Welcome banner when you restart the container.
Rolling back a patch
- Invoke the patch:list command to obtain the patch ID,
PatchID
, of the most recently installed patch. - Invoke the patch:rollback command, as follows:
patch:rollback PatchID
In some cases the container will need to restart to roll back the patch. In these cases, the container restarts automatically. Due to the highly dynamic nature of the OSGi runtime, during the restart you might see some occasional errors related to incompatible classes. These are related to OSGi services that have just started or stopped. These errors can be safely ignored.
Adding features to an incrementally patched container
19.5. Patching a Custom Assembly
Overview
Custom assembly
quickstart/custom
template. The custom assembly deploys a customized set of Karaf features and can be used to cut down the size of a JBoss Fuse deployment.
Inverting the patching procedure
A rollup patch is a JBoss Fuse distribution
Generating a patched custom assembly
19.6. Patching a Fabric Container with a Rollup Patch
Abstract
Overview
- Distribution of patched artifacts
- Profiles
- Configuration of the underlying container
Root container
patch:*
commands from the console of the root container. If you are planning to distribute patch artifacts through the Maven proxy, it is convenient to choose the root container to be the ensemble container that is currently the master of the Maven proxy cluster (see Chapter 20, Fabric Maven Proxies). This would ensure that patch artifacts can immediately be downloaded by other containers in the cluster.
Distribution of patch artifacts
- Through the Maven proxy (default approach)—when you add a rollup patch to your root container (using the
patch:add
command), the patch artifacts are installed into the root container'ssystem/
directory, whose directory structure is laid out like a Maven repository. The root container can then serve up these patch artifacts to remote containers by behaving as a Maven proxy, enabling remote containers to download the required Maven artifacts (this process is managed by the Fabric agent running on each Fabric container). Alternatively, if you have installed the rollup patch to a container that is not hosting the Maven proxy, you can ensure that the patch artifacts are uploaded to the Maven proxy by invoking thepatch:fabric-install
command with the--upload
option.There is a limitation to the Maven proxy approach, however, if the Fabric ensemble consists of multiple containers. In this case, it can happen that the Maven proxy fails over to a different ensemble container (not the original root container). This can result in the patch artifacts suddenly becoming unavailable to other containers in the fabric. If this occurs during the patching procedure, it will cause problems.NoteContainers that are added to an ensemble do not automatically deploy the Maven proxy. To enable the Maven proxy, make sure that thefabric
profile is deployed in the container.For more details, see chapter "Fabric Maven Proxies" in "Fabric Guide". - Through a local repository (recommended approach)—to overcome the limitations of the Maven proxy approach, we recommend that you make the patch artifacts available directly to all of the containers in the Fabric by setting up a local repository on the file system. Assuming that you have a networked file system, all containers will be able to access the patch artifacts directly.For example, you might set up a local repository of patch artifacts, as follows:
- Given a rollup patch file, extract the contents of the
system/
directory from the rollup patch file into therepositories/
subdirectory of a local Maven repository (which could be~/.m2/repositories
or any other location). - Configure the Fabric agent and the Maven proxy to pick up artifacts from the local repository by editing the current version of the
default
profile, as follows:profile-edit --append --pid io.fabric8.agent/org.ops4j.pax.url.mvn.defaultRepositories="file:///PathToRepository" default
ReplacePathToRepository
by the actual location of the local repository on your file system.NoteMake sure that you make the edits to thedefault
profile for all relevant profile versions. If some of your containers are using a non-default profile version, repeat theprofile-edit
commands while specifying the profile version explicitly as the last parameter.
Profiles
default
, fabric
, karaf
, and so on), the patching mechanism attempts to merge your changes with the changes introduced by the patch.
default
profile).
Configuration of the underlying container
etc/
, lib/
, and so on). When a Fabric container is upgraded to a patched version (for example, using the fabric:container-upgrade
command), the container's Fabric agent checks whether the underlying container must be patched. If yes, the Fabric agent triggers the patching mechanism to update the underlying container. Moreover, if certain critical files are updated (for example, lib/karaf.jar
), the container status changes to requires full restart
after the container is upgraded. This status indicates that a full manual restart is required (an automatic restart is not possible in this case).
io.fabric.version in the default profile
io.fabric.version
resource in the default
profile plays a key role in the patching mechanism. This resource defines the version and build of JBoss Fuse and of all of its main components. When upgrading (or rolling back) a Fabric container to a new version, the Fabric agent checks the version and build of JBoss Fuse as defined in the io.fabric.version
resource. If the JBoss Fuse version changes between the original profile version and the upgraded profile version, the Fabric agent knows that an upgrade of the underlying container is required when upgrading to this profile version.
Patching the patch mechanism
- Download the appropriate patch management package. From the JBoss Fuse 6.3.0 Software Downloads page, select a package named Red Hat JBoss Fuse 6.3.0 Rollup N on Karaf Update Installer, where N is the number of the particular rollup patch you are about to install.ImportantThe rollup number, N, of the downloaded patch management package must match the rollup number of the rollup patch you are about to install. For some rollup patches, there is no corresponding patch management package, in which case you can skip directly to the instructions for installing the rollup patch.
- Extract the contents of the patch management package,
patch-management-for-fuse-630-TargetVersion.zip
, on top of the root container (that is, on top of the Fabric container that will be used to perform the remainder of the patching tasks). Use an archive utility to extract the contents on top of the root container installation, merging the contents of the archivesystem/
andpatches/
directories with the containersystem/
andpatches/
subdirectories.NoteIt does not matter whether the root container is running when you extract these files. - Start the root container, if it is not already running.
- Create a new version, using the
fabric:version-create
command (where we assume that the current profile version is1.0
):JBossFuse:karaf@root> fabric:version-create --parent 1.0 1.0.1 Created version: 1.0.1 as copy of: 1.0
ImportantVersion names are important! The tooling sorts version names based on the numeric version string, according to major.minor numbering, to determine the version on which to base a new one. You can safely add a text description to a version name as long as you append it to the end of the generated default name like this:1.3 [.description]
. If you abandon the default naming convention and use a textual name instead (for example, Patch051312), the next version you create will be based, not on the last version (Patch051312), but on the highest-numbered version determined by dot syntax. - Update the
patch
property in theio.fabric8.version
PID in the version1.0.1
of thedefault
profile, by entering the following Karaf console command:profile-edit --pid io.fabric8.version/patch=1.2.0.redhat-630xxx default 1.0.1
Where you must replace1.2.0.redhat-630xxx
with the actual build version of the patch commands you are installing (for example, the build versionxxx
can be taken from the last three digits of theTargetVersion
in the downloaded patch management package file name). - Upgrade the root container to use the new patching mechanism, as follows:
container-upgrade 1.0.1 root
- Likewise, for all other containers in your fabric that need to be patched (SSH, child, and so on), provision them with the new patching mechanism by upgrading them to profile version
1.0.1
. For example:container-upgrade 1.0.1 container1 container2 container3
-
After completing the container-upgrade, if
patch
commands are unavailable or if the console issues a prompt that a container restart is necessary, then restart the upgraded containers to complete the upgrade process.
Applying a rollup patch
- Before applying the rollup patch to your fabric, you must patch the patch mechanism, as described in the section called “Patching the patch mechanism”.
- For every top-level container (that is, any container that is not a child container), perform these steps, one container at a time:
- In the corresponding Karaf installation, remove the
lib/endorsed/org.apache.karaf.exception-2.4.0.redhat-630xxx.jar
file (where the build number,xxx
, depends on the build being patched). - Restart the container.
- Add the patch to the root container's environment using the patch:add command. For example, to add the
patch.zip
patch file:JBossFuse:karaf@root> patch:add file://patch.zip [name] [installed] [description] PatchID false Description
ImportantIf you have decided to use a local repository to distribute the patch artifacts (recommended), set up the local repository now—see the section called “Distribution of patch artifacts”. - Create a new version, using the
fabric:version-create
command:JBossFuse:karaf@root> fabric:version-create 1.1 Created version: 1.1 as copy of: 1.0.1
ImportantVersion names are important! The tooling sorts version names based on the numeric version string, according to major.minor numbering, to determine the version on which to base a new one. You can safely add a text description to a version name as long as you append it to the end of the generated default name like this:1.3[.description]
. If you abandon the default naming convention and use a textual name instead (for example, Patch051312), the next version you create will be based, not on the last version (Patch051312), but on the highest-numbered version determined by dot syntax. - Apply the patch to the new version, using the
patch:fabric-install
command. Note that in order to run this command you must provide the credentials,Username
andPassword
, of a user withAdministrator
privileges. For example, to apply thePatchID
patch to version1.1
:patch:fabric-install --username Username --password Password --upload --version 1.1 PatchID
NoteWhen you invoke thepatch:fabric-install
command with the--upload
option, Fabric looks up the ZooKeeper registry to discover the URL of the currently active Maven proxy, and uploads all of the patch artifacts to this URL. Using this approach it is possible to make the patch artifacts available through the Maven proxy, even if the container you are currently logged into is not hosting the Maven proxy. - Delete the old bundle overrides created by the old hot fix patch by modifying the parent profiles of the profile default and removing the old hot fix patch profile as being a parent of the default profile. For example,
JBossFuse:karaf@root> fabric:profile-display --version 1.X default Attributes: parents: acls patch-jboss-fuse-6.2.1.redhat-186-12-r7hf10 JBossFuse:karaf@root> fabric:profile-change-parents --version 1.X default acls
NoteThe parentpatch-jboss-fuse-6.2.1.redhat-186-12-r7hf10
is only visible if a hot fix patch was installed previously. The name of the parent patch is different based on the hot fix patch.The above commands shows that default profile has two parents:- acls - standard and must be present.
- patch-jboss-fuse-6.2.1.redhat-186-12-r7hf10 - a profile that represents hotfix patch.
- Synchronize the patch information across the fabric, to ensure that the profile changes in version
1.1
are propagated to all containers in the fabric (particularly remote SSH containers). Enter the following console command:patch:fabric-synchronize
- Upgrade each existing container in the fabric using the
fabric:container-upgrade
command (but leaving the root container, where you installed the patch, until last). For example, to upgrade a container namedremote
, enter the following command:JBossFuse:karaf@root> fabric:container-upgrade 1.1 remote Upgraded container remote from version 1.0.1 to 1.1
At this point, not only does the Fabric agent download and install the patched bundles into the specified container, but the agent also applies the patch to the underlying container (updating any static files in the container, if necessary). If necessary, the agent will then restart the target container automatically or set the container status torequires full restart
(if an automatic restart is not possible), so that any changes made to the static files are applied to the running container.ImportantIt is recommended that you upgrade only one or two containers to the patched profile version, to ensure that the patch does not introduce any new issues. - If the current status of the upgraded container is
requires full restart
, you must now use one of the standard mechanisms to stop and restart the container manually. In some cases, it will be possible to do this using Fabric commands from the console of the root container.For example, you could stop theremote
container as follows:fabric:container-stop remote
And restart theremote
container as follows:fabric:container-start remote
- Upgrade the root container last (that is, the container that you originally installed the patch on):
fabric:container-upgrade 1.1 root
- (Windows only) If the root container status has changed to
requires full restart
and it is running on a Windows operating system, you must first shut down all of the root container's child containers (if any) before manually restarting the root container.For example, if the root container has three child containers,child1
,child2
, andchild3
, you would first shut them down, as follows:fabric:container-stop child1 child2 child3
You can then shut down the root container with theshutdown
command:shutdown
Rolling back a rollup patch
fabric:container-rollback
command. For example, assuming that 1.0
is an unpatched profile version, you can roll the remote
container back to the unpatched version 1.0
as follows:
fabric:container-rollback 1.0 remote
requires full restart
(if an automatic restart is not possible), so that any changes made to the static files are applied to the running container.
19.7. Patching a Fabric Container with an Incremental Patch
Abstract
Overview
- Distribution of patched artifacts through Maven proxy
- Profiles
Distribution of patched artifacts through Maven proxy
system/
directory, whose directory structure is laid out like a Maven repository. The local container distributes these patch artifacts to remote containers by behaving as a Maven proxy, enabling remote containers to upload bundle JARs as needed (this process is managed by the Fabric agent running on each Fabric container). For more details, see chapter "Fabric Maven Proxies" in "Fabric Guide".
Profiles
- The patch mechanism creates a new profile,
patch-PatchProfileID
, which defines bundle overrides for all of the patched bundles. - The new patch profile,
patch-PatchProfileID
, is inserted as the parent of thedefault
profile (at the base of the entire profile tree). - All of the profiles that inherit from default now use the bundle versions defined by the overrides in
patch-PatchProfileID
. The contents of the existing profiles themselves are not modified in any way.
Is it necessary to patch the underlying container?
fabric:create
command). Always read the patch README
file to find out whether there are any special steps required to install a particular patch. In these cases, however, it is more likely that the patch would be distributed in the form of a rollup patch, which has the capability to patch the underlying container automatically—see Section 19.6, “Patching a Fabric Container with a Rollup Patch”.
Applying an incremental patch
- Before you proceed to install the incremental patch, make sure to read the text of the
README
file that comes with the patch, as there might be additional manual steps required to install a particular incremental patch. - Create a new version, using the
fabric:version-create
command:JBossFuse:karaf@root> fabric:version-create 1.1 Created version: 1.1 as copy of: 1.0
ImportantVersion names are important! The tooling sorts version names based on the numeric version string, according to major.minor numbering, to determine the version on which to base a new one. You can safely add a text description to a version name as long as you append it to the end of the generated default name like this:1.3 <.description >
.If you abandon the default naming convention and use a textual name instead (for example, Patch051312), the next version you create will be based, not on the last version (Patch051312), but on the highest-numbered version determined by dot syntax. - Apply the patch to the new version, using the
fabric:patch-apply
command. For example, to apply theactivemq.zip
patch file to version1.1
:JBossFuse:karaf@root> fabric:patch-apply --version 1.1 file:///patches/activemq.zip
- Upgrade a container using the
fabric:container-upgrade
command, specifying which container you want to upgrade. For example, to upgrade thechild1
container, enter the following command:JBossFuse:karaf@root> fabric:container-upgrade 1.1 child1 Upgraded container child1 from version 1.0 to 1.1
ImportantIt is recommended that you upgrade only one or two containers to the patched profile version, to ensure that the patch does not introduce any new issues. Upgrade theroot
container (the one that you applied the patch to, using thefabric:patch-apply
command) last. - You can check that the new patch profile has been created using the
fabric:profile-list
command, as follows:BossFuse:karaf@root> fabric:profile-list --version 1.1 | grep patch default 0 patch-activemq-patch patch-activemq-patch
Where we presume that the patch was applied to profile version 1.1.NoteIf you want to avoid specifying the profile version (with--version
) every time you invoke a profile command, you can change the default profile version using thefabric:version-set-default Version
command.You can also check whether specific JARs are included in the patch, for example:JBossFuse:karaf@root> list | grep -i activemq [ 131] [Active ] [Created ] [ ] [ 50] activemq-osgi (5.9.0.redhat-61037X) [ 139] [Active ] [Created ] [ ] [ 50] activemq-karaf (5.9.0.redhat-61037X) [ 207] [Active ] [ ] [ ] [ 60] activemq-camel (5.9.0.redhat-61037X)
Rolling back an incremental patch
fabric:container-rollback
command. For example, assuming that 1.0
is an unpatched profile version, you can roll the child1
container back to the unpatched version 1.0
as follows:
fabric:container-rollback 1.0 child1
Chapter 20. Fabric Maven Proxies
Abstract
20.1. Introduction to Fabric Maven Proxies
Overview
fabric
profile. The fabric
profile, as well as any profile that inherits from the fabric
profile, contains the fabric-maven-bundle
, which enables a container to be a Maven proxy. Containers that can be Maven proxies include:
- Fabric servers
- Containers that are joined to a cluster with
fabric:join
and that keep the assignedfabric
profile - Containers that are provisioned with a profile that inherits from the
fabric
profile
fabric
profile registers itself in Zookeeper as a Maven proxy. When a container is being provisioned, its fabric-agent
bundle obtains the list of Maven proxies from Zookeeper and prepends their URIs to the container's io.fabric8.agent/org.ops4j.pax.url.mvn.repositories
list. When the container needs a Maven artifact, it uses the entire list of Maven proxies. Consequently, you should not use too many containers that run the fabric
profile and are therefore Maven proxies. For example, if there are 100 containers and one of them cannot resolve a particular artifact, it is probable that none of the other containers can resolve it either but they could all be consulted.
Maven proxy
- The Maven proxy builds up a large cache over time, which can be served up quickly to other containers in the Fabric.
- It is not necessary for every container to download Maven artifacts from remote repositories—the Maven proxy performs this service for the other containers.
- In a network with limited Internet access, you can arrange to deploy the Maven proxy on a host with Internet access, while the other containers in the fabric are deployed on hosts without Internet access.
Managed container
Fabric8 agent
Resolving a Maven artifact
- Default repositories, which are local repositories for the Fabric agent.
- Maven proxy.
- Remote Maven repositories.
Maven proxy endpoint discovery
/fabric/registry/maven/proxy/download
path in Zookeeper).
No replication
- Any client that does not have the complete list of Maven proxy URLs would need to be reconfigured manually to use one of the remaining available Maven proxies.
- If you have been automatically uploading artifacts to the Maven proxy as part of your build process (see Section 20.7, “Automated Deployment”), you will need to reconfigure the upload URL.
- It is likely that the next Maven proxy has a much smaller cache of Maven artifacts than the original one. This could result in noticeable delays, because many previously cached artifacts have to be downloaded again.
Managing the Maven artifact data
${karaf.home}/data/repository
). You could simply do a manual copy of the contents of the local Maven repository from one Maven proxy host to another. Or for a more sophisticated approach, you could try storing the local Maven repository on a networked file system.
20.2. How a Managed Container Resolves Artifacts
Overview
io.fabric8.agent
PID's org.ops4j.pax.url.mvn.defaultRepositories
property or org.ops4j.pax.url.mvn.localRepository
property), it tries to download the needed artifact from one of the remote repositories, starting with the Maven proxies. In other words, downloading from a Maven proxy is the primary mechanism for managed containers to obtain new artifacts.
Fabric profiles drive bundle provisioning
bundle.BundleName
entry to the profile's agent properties. Provisioning can also be triggered when you edit other resources (not directly associated with OSGi Config Admin) in a profile—for example, by referencing a resource through a checksum property resolver (see ???).
Fabric8 agent
mvn
URL scheme, the Fabric8 agent is responsible for locating these new bundles through Maven. In the context of Fabric, the Fabric8 agent effectively plays the same role that the Pax URL Aether component plays in a standalone (non-Fabric) container.
mvn
URL, reads the relevant Maven configuration properties, and calls directly into the Eclipse Aether layer to resolve the referenced artifact.
Eclipse Aether layer
Provisioning a managed container
Figure 20.1. Provisioning a Managed Container
Provisioning steps
- Provisioning of a profile is triggered when the properties of a current profile are updated. In particular, whenever new bundles or features are added to a profile, the Fabric8 agent is responsible for resolving the new Maven artifacts (referenced through the
mvn
URL protocol). - The Fabric8 agent reads its Maven configuration from the
io.fabric8.agent
PID in thedefault
profile (and possibly also from themaven-settings.xml
file, if so configured). - The Fabric8 agent contacts Zookeeper to discover the URLs of the Fabric8 Maven proxy instances—see Section 20.1, “Introduction to Fabric Maven Proxies”. The Fabric8 agent then inserts the list of Maven proxy URLs at the head of the list of remote Maven repositories.The Fabric8 agent parses the requested
mvn
URL and combines this information with the specified configuration—including the list of Maven proxy URLs—in order to invoke the Eclipse Aether library. - When the Aether library is invoked, the first step is to look up the Maven default repositories to try and find the Maven artifact. The following default repositories are configured by default:
InstallDir/system
- The JBoss Fuse system directory, which contains all of the Maven artifacts bundled with the JBoss Fuse distribution.
InstallDir/data/maven/upload
- If this container is an ensemble container (running a Maven proxy), this directory would contain any artifacts explicitly uploaded to the Maven proxy. In a managed container, this directory is normally empty.
UserHome/.m2/repository
- The user's own local Maven repository in the user's home directory,
UserHome
.
If the Maven artifact is found in a default repository, skip straight to step 8. - The Aether library now begins the process of consulting the remote repositories (as specified by the
io.fabric8.agent/org.ops4j.pax.url.mvn.repositories
PID property and augmented by the list of Maven proxy URLs). This process works in tandem with the local Maven repository (as specified by theio.fabric8.agent/org.ops4j.pax.url.mvn.localRepository
PID property), which acts as a cache for the remote repositories.The Aether library searches the repositories in the following order:- Local Maven repository—by default,
InstallDir/data/repository-agent
, - Maven proxies—iterating over the list of Maven proxy URLs added to the
org.ops4j.pax.url.mvn.repositories
argument.
NoteIf you are using a HTTP proxy, you should configure the Fabric8 agent to bypass the HTTP proxy when it accesses the Maven proxy hosts. To bypass the HTTP proxy in this case, configure the Maven proxy hosts to be HTTP non-proxy hosts—see the section called “Configuring an HTTP proxy”. - The Aether library continues the process of consulting the remote repositories, by accessing the remote repositories configured in the
io.fabric8.agent/org.ops4j.pax.url.mvn.repositories
PID property.NoteIf your local network requires you to use a HTTP proxy to access the Internet, it is possible to configure Fabric8 to use a HTTP proxy. For example, see the section called “Configuring an HTTP proxy” for details. - If the Maven artifact is found in the Maven proxy or in a remote repository, Aether automatically installs the artifact into the local Maven repository,
InstallDir/data/repository-agent
, so that another remote lookup will not be required. - Finally, assuming that the Maven artifact has been successfully resolved, Karaf installs the artifact in the Karaf bundle cache,
InstallDir/data/cache
, and loads the artifact (usually, an OSGi bundle) into the container runtime. At this point, the artifact is effectively installed in the container.
io.fabric8.agent configuration
io.fabric8.agent
PID (also known as agent properties). The Maven properties are normally set in the default
profile, which ensures that the same settings are used throughout the entire fabric (recommended).
default
profile using the fabric:profile-display
command, as follows:
JBossFuse:karaf@root> profile-display default ... Agent Properties : ... org.ops4j.pax.url.mvn.globalUpdatePolicy = daily org.ops4j.pax.url.mvn.defaultRepositories = file:${runtime.home}/${karaf.default.repository}@snapshots@id=karaf-default, file:${runtime.data}/maven/upload@snapshots@id=fabric-upload, file:${user.home}/.m2/repository@snapshots@id=local ... org.ops4j.pax.url.mvn.globalChecksumPolicy = warn org.ops4j.pax.url.mvn.settings = ${karaf.etc}/maven-settings.xml ... org.ops4j.pax.url.mvn.localRepository = ${karaf.data}/repository-agent ... org.ops4j.pax.url.mvn.repositories = http://repo1.maven.org/maven2@id=maven.central.repo, https://maven.repository.redhat.com/ga@id=redhat.ga.repo, https://maven.repository.redhat.com/earlyaccess/all@id=redhat.ea.repo, https://repository.jboss.org/nexus/content/groups/ea@id=fuseearlyaccess ...
org.ops4j.pax.url.mvn.*
are the Maven properties used by the Fabric8 agent.
org.ops4j.pax.url.mvn.*
properties are not related to the Pax URL Aether component. There is some potential for confusion here, because the Fabric8 agent uses the same property names as Pax URL Aether. These properties are read by the Fabric8 agent, however, not by Pax URL Aether (and are associated with the io.fabric8.agent
PID, not the org.ops4j.pax.url.mvn
PID).
20.3. How a Maven Proxy Resolves Artifacts
Overview
Fabric8 Maven proxy server
Host
, the Maven proxy can be accessed through the following URL:
http://Host:8181/maven/download
io.fabric8.maven
PID and these properties are normally set in the default
profile (recommended).
io.fabric8.maven.proxy
PID, but these properties do not play an important role in artifact resolution.
Serving artifacts through the Maven proxy
Figure 20.2. Maven Proxy Serving an Artifact
Steps to serve artifacts
- Resolution of a Maven artifact is triggered when a managed container sends a request to the Maven proxy server.
- The Maven proxy server parses the incoming HTTP request and then makes a call to the
io.fabric8.maven
layer, asking it to resolve the requested Maven artifact. - The
io.fabric8.maven
layer reads its Maven configuration from theio.fabric8.maven
PID in thedefault
profile (and possibly also from themaven-settings.xml
file, if so configured). - When the Aether library is invoked, the first step is to look up the Maven default repositories to try and find the Maven artifact. The following default repositories are configured by default:
InstallDir/system
- The JBoss Fuse system directory, which contains all of the Maven artifacts that are bundled with the JBoss Fuse distribution.
InstallDir/data/maven/upload
- The Maven proxy's upload directory, which is used to store artifacts that have been directly uploaded to the Maven proxy—see Section 20.7, “Automated Deployment”.
UserHome/.m2/repository
- The user's own local Maven repository in the user's home directory,
UserHome
.
If the Maven artifact is found locally, skip straight to step 7. - The Aether library now begins the process of consulting the remote repositories (as specified by the
io.fabric8.maven/io.fabric8.maven.repositories
PID property which references theio.fabric8.agent/org.ops4j.pax.url.mvn.repositories
PID property). This process works in tandem with the local Maven repository (as specified by theio.fabric8.maven/io.fabric8.maven.localRepository
PID property), which acts as a cache for the remote repositories.NoteIf your local network requires you to use a HTTP proxy to access the Internet, it is possible to configure Fabric8 to use a HTTP proxy. For example, see the section called “Configuring an HTTP proxy” for details. - If the Maven artifact is found in a remote repository, Aether automatically installs the artifact into the local Maven repository,
InstallDir/data/repository
, so that another remote lookup will not be required. - The Maven proxy server returns the successfully located Maven artifact to the client (or an error message, if the artifact could not be found).
20.4. Configuring Maven Proxies Directly
Overview
io.fabric8.agent
PID and the io.fabric8.maven
PID. Because these properties are set in a profile, they are immediately available to all containers in a fabric.
org.ops4j.pax.url.mvn.repositories
property in the io.fabric8.agent
PID. If this property is not set, the Fabric8 agent falls back to reading configuration from the Maven settings file, InstallDir/etc/maven-settings.xml
file.
Tools for editing configuration
fabric:profile-edit
). It is worth recalling, however, that there are several different tools you can use to modify the settings in a fabric:
- Karaf console—use the
fabric:*
family of commands (for example,fabric:profile-edit
). - Fuse Management Console (Hawtio)—you can edit profile settings through the Profile tab or the Wiki tab in the Fabric perspective of the Hawtio console, http://localhost:8181/hawtio/login.
- Git configuration—you can edit profile settings by cloning the Git profile repository. See ??? for details.
Rolling out configuration changes
default
profile, as follows:
profile-edit --pid io.fabric8.agent/org.ops4j.pax.url.mvn.repositories='http://foo/bar@id=myfoo' --append default
1.0
):
version-create 1.1 profile-edit --pid io.fabric8.agent/org.ops4j.pax.url.mvn.repositories='http://foo/bar@id=myfoo' --append default 1.1
1.1
, using the following command:
container-upgrade 1.1 mycontainer
Adding a remote Maven repository
org.ops4j.pax.url.mvn.repositories
property of the io.fabric8.agent
PID in the default
profile (not forgetting to specify the mandatory @id
suffix in the repository URL).
http://foo/bar
Maven repository to the list of remote repositories, enter the following console command:
profile-edit --pid io.fabric8.agent/org.ops4j.pax.url.mvn.repositories='http://foo/bar@id=myfoo' --append default
- The preceding setting simultaneously updates the
io.fabric8.maven/io.fabric8.maven.repositories
property (which, by default, references theio.fabric8.agent/org.ops4j.pax.url.mvn.repositories
property), which configures the Maven proxy. - By editing this property in the
default
profile (which is normally the base profile of every profile), you ensure that this setting is propagated to all containers and to all Maven proxies in the Fabric. - The preceding command immediately changes the configuration of all containers at the current version. If you prefer to implement a phased rollout of the new configuration, use profile versions, as described in ???.
@id
option specifies the name of the repository and is required. You can choose an arbitrary value for this ID.
20.5. Configuring Maven Proxies and HTTP Proxies through settings.xml
Overview
settings.xml
file. For example, this approach is particularly convenient in a development environment, because it makes it possible to store your build time settings and your run time settings in one place.
settings.xml
approach is not used by default. You must explicitly enable it.
Adding a remote Maven repository
settings.xml
file is provided for you in InstallDir/etc/maven-settings.xml
. To add a new remote Maven repository to the InstallDir/etc/maven-settings.xml
file, open the maven-settings.xml
file in a text editor and add a new repository
XML element. For example, to create an entry for the Red Hat GA public Maven repository, add a repository
element as shown:
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd"> ... <!-- If org.ops4j.pax.url.mvn.repositories property is _prepended_ with '+' sign, repositories from all active profiles will be _appended_ to the list of searched remote repositories --> <profiles> <profile> <id>default</id> <repositories> <repository> <id>redhat-ga-repository</id> <url>https://maven.repository.redhat.com/ga</url> </repository> </repositories> </profile> </profiles> <activeProfiles> <activeProfile>default</activeProfile> </activeProfiles> </settings>
activeProfile
element that references the profile ID (in this example, the profile ID is default
).
Enabling the settings.xml configuration approach
settings.xml
file, perform the following steps:
- Configure the Maven repositories you need in the
InstallDir/etc/maven-settings.xml
file (see the section called “Adding a remote Maven repository”). - Copy the Maven repositories from the
io.fabric8.agent/org.ops4j.pax.url.mvn.settings
property into themaven-settings.xml
file (normally, you need to preserve access to these repositories). To see the list of repositories from theio.fabric8.agent/org.ops4j.pax.url.mvn.settings
property in thedefault
profile, enter the following Fabric8 command:JBossFuse:karaf@root> profile-display default
Follow the instructions in the section called “Adding a remote Maven repository” to add these repositories set inio.fabric8.agent/org.ops4j.pax.url.mvn.settings
to themaven-settings.xml
file (if they are not already present). - (Optional) If you want to combine the list of repositories appearing in the
maven-settings.xml
file with the list of repositories from theio.fabric8.maven/io.fabric8.maven.repositories
property, prepend a+
sign to the list of repositories inio.fabric8.maven.repositories
. For example:io.fabric8.maven.repositories=+http://repo1.maven.org/maven2@id=maven.central.repo,https://maven.repository.redhat.com/ga@id=redhat.ga.repo,https://maven.repository.redhat.com/earlyaccess/all@id=redhat.ea.repo,https://repository.jboss.org/nexus/content/groupsea@id=fuseearlyaccess
- Delete the
org.ops4j.pax.url.mvn.repositories
property setting from theio.fabric8.agent
PID in thedefault
profile, using the following console command:profile-edit --delete --pid io.fabric8.agent/org.ops4j.pax.url.mvn.repositories default
When the repositories setting is absent, Fabric implicitly switches to themaven-settings.xml
configuration approach.NoteBy default, this step simultaneously clears both the repository list used by the Fabric8 agent and the repository list used by the Maven proxy server (because the Maven proxy's repository list normally references the Fabric8 agent's repository list).
Changing the default location of Maven settings.xml
InstallDir/etc/maven-settings.xml
file. That is, the following settings are configured by default:
io.fabric8.maven/io.fabric8.maven.settings = ${karaf.etc}/maven-settings.xml io.fabric8.agent/org.ops4j.pax.url.mvn.settings = ${karaf.etc}/maven-settings.xml
settings.xml
file, edit the value of these properties in the default
profile.
Configuring an HTTP proxy
etc/maven-settings.xml
file in a text editor and add a new proxy
XML element as a child of the proxies
XML element. The definition of the proxy follows the standard Maven syntax. For example, to create a proxy for the HTTP (insecure) protocol with host, 127.0.0.1
, and port, 3128
, add a proxy
element as follows:
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd"> ... <!-- This is the place to configure http proxies used by Aether. If there's no proxy for "https" protocol, proxy for "http" will be used when accessing remote repository --> <proxies> <!-- <proxy> <id>proxy</id> <host>127.0.0.1</host> <port>3128</port> <protocol>http</protocol> <username></username> <password></password> <nonProxyHosts>127.0.0.*|ensemble1|ensemble2|ensemble3</nonProxyHosts> </proxy> --> </proxies> ... </settings>
nonProxyHosts
element. This ensures that the Fabric8 agents do not attempt to connect to the Maven proxies through the HTTP proxy, but make a direct connection instead. In the preceding example, the ensemble host names are ensemble1
, ensemble2
, and ensemble3
.
proxy
element configured with the https
protocol.
Reference
settings.xml
file, see the Maven Settings Reference. But please note that not all of the features documented there are necessarily supported by Fabric.
20.6. Securely Accessing Maven Repositories
Overview
default
container profile.
Obtain encrypted Maven passwords
default
profile has the maven-settings.xml
template file and the maven-settings-secure.xml
template file. You need to update these files to specify encrypted Maven passwords. Before you can do that, you must obtain an encryption of the master Maven password and and an encryption of the ordinary Maven password as follows:
- Invoke the
fabric:maven-password
command to view Maven security settings:JBossFuse:karaf@root> fabric:maven-password Maven security configuration in Fabric environment defined in io.fabric8.maven and io.fabric8.agent PID. Security settings file: /data/servers/jboss-fuse-6.3.0.redhat-311/etc/maven-settings-security.xml Encrypted Maven master password: {PMFs1x/vuOMHhjzIZpzst/d5Kpna+WqNu3P15ZcIP8g=}
- Decrypt the master Maven password that is in the security settings:
JBossFuse:karaf@root> fabric:maven-password -d Maven security configuration in Fabric environment defined in io.fabric8.maven and io.fabric8.agent PID. Security settings file: /data/servers/jboss-fuse-6.3.0.redhat-311/etc/maven-settings-security.xml Decrypted Maven master password: fabric:changeit
- Obtain an encryption for the master Maven password by entering it twice at the prompts:
JBossFuse:karaf@root> fabric:maven-password --encrypt-master-password Master Maven password: Verify master Maven password: Encrypted master Maven password to use in security-settings.xml: {94gq/tbm0IYHZl4M6BstgfnY/iErAy+GKlfXiptLL/Q=}
- Obtain an encryption for the regular Maven password:
JBossFuse:karaf@root> fabric:maven-password --encrypt-password Looking up master Maven password in /data/servers/jboss-fuse-6.3.0.redhat-311/etc/maven-settings-security.xml... Done! Maven password: Verify Maven password: Encrypted Maven password to use in settings.xml for server and proxy authentication: {WCUxIVlatO4HZG2xrqtVBziJIeDTTuVK1oCNEA2eKEQ=}
Procedure
- Obtain an encrypted master Maven password and an encrypted regular Maven password, as described in the previous section.
- In the
default
profile, configureio.fabric8.agent.properties/org.ops4j.pax.url.mvn.repositories
as follows:org.ops4j.pax.url.mvn.repositories= http://localhost:8081/repository/maven-releases@id=nexus
- In the
default
profile, edit themaven-settings.xml
file to specify the encrypted regular Maven password. For example:<servers> <server> <id>nexus</id> <username>developer</username> <password>{WCUxIVlatO4HZG2xrqtVBziJIeDTTuVK1oCNEA2eKEQ}</password> </server> ... </servers>
- In the
default
profile, edit themaven-settings-security.xml
file to specify the encrypted master Maven password. For example:<settingsSecurity> <master>{94gq/tbm0IYHZl4M6BstgfnY/iErAy+GKlfXiptLL/Q=}</master> </settingsSecurity>
- Refresh the
default
profile so thatfabric-agent
uses the updated configuration:profile-refresh default
- Restart the
fabric-maven
bundle so that the updates are available to the Maven URI handler and to thefabric-maven-proxy
bundle:bundle:stop io.fabric8.fabric-maven bundle:start io.fabric8.fabric-maven
20.7. Automated Deployment
Overview
Discover the upload URL of the current master
fabric:cluster-list
command, as follows:
JBossFuse:karaf@root> cluster-list servlets/io.fabric8.fabric-maven-proxy [cluster] [masters] [slaves] [services] [] 1.2.0.redhat-621084/maven/download root root - http://127.0.0.1:8181/maven/download 1.2.0.redhat-621084/maven/upload root root - http://127.0.0.1:8181/maven/upload
http://127.0.0.1:8181/maven/upload
.
Manually deploy a Maven project
mvn deploy
with the altDeploymentRepository
command-line option. The value of altDeploymentRepository
is specified in the following format:
ID::Layout::RepositoryURL
ID
- Can be used to pick up the relevant credentials from the
settings.xml
file (from the matchingsettings/servers/server/id element
). Otherwise, the credentials must be specified in the repository URL. If necessary, you can simply specify a dummy value for the ID. Layout
- Can be either
default
(for Maven3 or Maven2) orlegacy
(for Maven1, which is not compatible with JBoss Fuse). RepositoryURL
- The Maven proxy upload URL. For example,
http://User:Password@localhost:8181/maven/upload/
.
127.0.0.1
), authenticating with the admin/admin credentials, enter a command like the following:
mvn deploy -DaltDeploymentRepository=releaseRepository::default::http://admin:admin@127.0.0.1:8181/maven/upload/
Automatically deploy a Maven project
20.8. Fabric Maven Configuration Reference
Overview
io.fabric8.agent
PID, the io.fabric8.maven
PID, and the io.fabric8.maven.proxy
PID.
Repository URL syntax
file:
, http:
, or https:
scheme, optionally appending one or more of the following suffixes:
@snapshots
- Allow snapshot versions to be read from the repository.
@noreleases
- Do not allow release versions to be read from the repository.
@id=RepoName
- (Required) Specifies the repository name. This setting is required by the Aether handler.
@multi
- Marks the path as a parent directory of multiple repository directories. At run time the parent directory is scanned for subdirectories and each subdirectory is used as a remote repository.
@update=UpdatePolicy
- Specifies the Maven
updatePolicy
, overriding the value oforg.ops4j.pax.url.mvn.globalUpdatePolicy
. @releasesUpdate=UpdatePolicy
- Specifies the Maven
updatePolicy
specifically for release artifacts (overriding the value of@update
). @snapshotsUpdate=UpdatePolicy
- Specifies the Maven
updatePolicy
specifically for snapshot artifacts (overriding the value of@update
). @checksum=ChecksumPolicy
- Specifies the Maven
checksumPolicy
, which specifies how to react if a downloaded Maven artifact has a missing or incorrect checksum. The policy value can be:ignore
,fail
, orwarn
. @releasesChecksum=ChecksumPolicy
- Specifies the Maven
checksumPolicy
specifically for release artifacts (overriding the value of@checksum
). @snapshotsChecksum=ChecksumPolicy
- Specifies the Maven
checksumPolicy
specifically for snapshot artifacts (overriding the value of@checksum
).
https://repo.example.org/maven/repository@id=example.repo
io.fabric8.agent PID
io.fabric8.agent
PID configures the Fabric8 agent. The io.fabric8.agent
PID supports the following properties relating specifically to Maven configuration:
org.ops4j.pax.url.mvn.connection.bufferSize
- Configure buffer size for HTTP connections (output and input buffers), defaults to 8192 bytes.
org.ops4j.pax.url.mvn.connection.retryCount
- Number of connection retries after failure is detected in HTTP client. Default is
3
. org.ops4j.pax.url.mvn.defaultRepositories
- Specifies a list of default (local) Maven repositories that are checked before looking up the remote repositories. Specified as a comma-separated list of
file:
repository URLs, where each repository URL has the syntax defined in the section called “Repository URL syntax”. org.ops4j.pax.url.mvn.globalChecksumPolicy
- Specifies the Maven
checksumPolicy
. Thedefault
profile sets this property towarn
. org.ops4j.pax.url.mvn.globalUpdatePolicy
- Specifies the Maven
updatePolicy
, which determines how often Aether attempts to update local Maven artifacts from remote repositories. Can take the following values:always
—always resolve the latest SNAPSHOT from remote Maven repositories.never
—never check for newer remote SNAPSHOTS.daily
—check on the first run of the day (local time).interval:Mins
—check everyMins
minutes.
Thedefault
profile sets this property todaily
. If not set, default isdaily
. org.ops4j.pax.url.mvn.localRepository
- Specifies the local Maven repository, which is used to cache artifacts downloaded from remote repositories (as specified in
org.ops4j.pax.url.mvn.repositories
).Thedefault
profile sets this property to${karaf.data}/repository-agent
. org.ops4j.pax.url.mvn.repositories
- Specifies a list of remote Maven repositories that can be searched for Maven artifacts. This property can be used in any of the following ways:
- Use this property and disable
settings.xml
Normally, theorg.ops4j.pax.url.mvn.repositories
property is set as a comma-separated list of repository URLs, where the \ character can be used for line continuation. In this case, any Mavensettings.xml
file is ignored (that is, theorg.ops4j.pax.url.mvn.settings
property setting is ignored). For example, this property is set as follows in thedefault
profile:org.ops4j.pax.url.mvn.repositories = http://repo1.maven.org/maven2@id=maven.central.repo, https://maven.repository.redhat.com/ga@id=redhat.ga.repo, https://maven.repository.redhat.com/earlyaccess/all@id=redhat.ea.repo, https://repository.jboss.org/nexus/content/groups/ea@id=fuseearlyaccess
- Use
settings.xml
and disable this propertyIf you want to use a Mavensettings.xml
file to configure the list of remote repositories instead of this property, you must remove theorg.ops4j.pax.url.mvn.repositories
property settings from the profile. For example, assuming that this property is set in the default profile, you can delete it with the following command:profile-edit --delete --pid io.fabric8.agent/org.ops4j.pax.url.mvn.repositories default
org.ops4j.pax.url.mvn.settings
- Specifies a path on the file system to override the default location of the Maven
settings.xml
file. The Fabric8 agent resolves the location of the Mavensettings.xml
file in the following order:- The location specified by
org.ops4j.pax.url.mvn.settings
. ${user.home}/.m2/settings.xml
${maven.home}/conf/settings.xml
M2_HOME/conf/settings.xml
NoteAllsettings.xml
files are ignored, if theorg.ops4j.pax.url.mvn.repositories
property is set. org.ops4j.pax.url.mvn.socket.connectionTimeout
- Timeout in milliseconds when establishing a HTTP connection during artifact resolution.
org.ops4j.pax.url.mvn.socket.keepAlive
SO_KEEPALIVE
option for sockets. Defaults tofalse
.org.ops4j.pax.url.mvn.socket.linger
SO_LINGER
option for sockets. Defaults to-1
.org.ops4j.pax.url.mvn.socket.readTimeout
- Timeout in milliseconds when reading data after connecting to a remote repository.
org.ops4j.pax.url.mvn.socket.reuseAddress
SO_REUSEADDR
option for sockets. Defaults tofalse
.org.ops4j.pax.url.mvn.socket.tcpNoDelay
TCP_NODELAY
option for sockets. Defaults totrue
.org.ops4j.pax.url.mvn.timeout
- Default value for connection and read timeouts, when
socket.readTimeout
andsocket.connectionTimeout
are not specified.
io.fabric8.maven PID
io.fabric8.maven
PID configures the io.fabric8.maven
bundle (which is used by the Maven proxy server) and supports the following properties:
io.fabric8.maven.connection.bufferSize
- Configure buffer size for HTTP connections (output and input buffers), defaults to 8192 bytes.
io.fabric8.maven.connection.retryCount
- Number of connection retries after failure is detected in HTTP client. Default is
3
. io.fabric8.maven.defaultRepositories
- Specifies a list of default (local) Maven repositories that are checked before looking up the remote repositories. Specified as a comma-separated list of
file:
repository URLs, where each repository URL has the syntax defined in the section called “Repository URL syntax”.Thedefault
profile sets this property to reference theorg.ops4j.pax.url.mvn.defaultRepositories
property from theio.fabric8.agent
PID. io.fabric8.maven.globalChecksumPolicy
- Specifies the Maven
checksumPolicy
. Thedefault
profile sets this property towarn
. io.fabric8.maven.globalUpdatePolicy
- Specifies the Maven
updatePolicy
, which determines how often Aether attempts to update local Maven artifacts from remote repositories.Thedefault
profile sets this property todaily
. If not set, default isdaily
. io.fabric8.maven.localRepository
- Specifies the local Maven repository, which is used to cache artifacts downloaded from remote repositories (as specified in
io.fabric8.maven.repositories
).Thedefault
profile sets this property to${karaf.data}/repository
. io.fabric8.maven.proxies
- (Obsolete) This option does not work any more. In older Fabric8 releases it was used to configure a HTTP proxy port.
io.fabric8.maven.repositories
- Specifies a list of remote Maven repositories that can be searched for Maven artifacts. This setting normally references the contents of the
io.fabric8.agent/org.ops4j.pax.url.mvn.repositories
property.If you decide to use a Mavensettings.xml
file to configure the Fabric8 agent (see Section 20.5, “Configuring Maven Proxies and HTTP Proxies through settings.xml”), you can combine the remote repositories specified in this setting and the remote repositories configured in asettings.xml
file using a special syntax for the list of repository URLs. In this case, you prefix a single+
character to the comma-separated list of repository URLs, where the repository URLs are listed on a single line (the\
line continuation character is not supported in this syntax). For example:io.fabric8.maven.repositories=+http://repo1.maven.org/maven2@id=maven.central.repo,https://maven.repository.redhat.com/ga@id=redhat.ga.repo,https://maven.repository.redhat.com/earlyaccess/all@id=redhat.ea.repo,https://repository.jboss.org/nexus/content/groupsea@id=fuseearlyaccess
io.fabric8.maven.settings
- Specifies a path on the file system to override the default location of the Maven
settings.xml
file.Thedefault
profile sets this property to${karaf.etc}/maven-settings.xml
. io.fabric8.maven.useFallbackRepositories
- This option is deprecated and should always be set to
false
.Thedefault
profile sets this property tofalse
. io.fabric8.maven.socket.connectionTimeout
- Timeout in milliseconds when establishing a HTTP connection during artifact resolution.
io.fabric8.maven.socket.keepAlive
SO_KEEPALIVE
option for sockets. Defaults tofalse
.io.fabric8.maven.socket.linger
SO_LINGER
option for sockets. Defaults to-1
.io.fabric8.maven.socket.readTimeout
- Timeout in milliseconds when reading data after connecting to a remote repository.
io.fabric8.maven.socket.reuseAddress
SO_REUSEADDR
option for sockets. Defaults tofalse
.io.fabric8.maven.socket.tcpNoDelay
TCP_NODELAY
option for sockets. Defaults totrue
.io.fabric8.maven.timeout
- Default value for connection and read timeouts, when
socket.readTimeout
andsocket.connectionTimeout
are not specified.
io.fabric8.maven.proxy PID
io.fabric8.maven.proxy
PID configures the Fabric8 Maven proxy server and supports the following properties:
appendSystemRepos
- The
fabric
profile sets this property tofalse
. role
- Specifies a comma-separated list of security roles that are allowed to access the Maven proxy server. For details of role-based access control, see section "Role-Based Access Control" in "Security Guide".The
default
profile sets this property to the following list:admin,manager,viewer,Monitor,Operator,Maintainer,Deployer,Auditor,Administrator,SuperUser
updatePolicy
- Specifies the Maven
updatePolicy
.Thefabric
profile sets this property toalways
. uploadRepository
- Specifies the location of the directory used to store artifacts uploaded to the Maven proxy server.The
fabric
profile sets this property to${runtime.data}/maven/upload
.
Chapter 21. Maven Indexer Plugin
Procedure 21.1. Deploy the Maven Indexer Plugin
- In the Container perspective go to the Karaf console and enter the following command to install the Maven Indexer plugin:
features:install hawtio-maven-indexer
In the Fabric perspective go to the Karaf console and add the feature to a profile:fabric:profile-edit --features hawtio-maven-indexer jboss-fuse-full
- For both perspectives, the rest of the commands are the same. Enter the following commands to configure the Maven Indexer plugin:
config:edit io.hawt.maven.indexer config:proplist config:propset repositories 'https://maven.oracle.com' config:proplist config:update
- Wait for the Maven Indexer plugin to be deployed. This may take a few minutes. Look out for messages like those shown below to appear on the log tab.
config:edit io.hawt.maven.indexer config:proplist config:propset repositories external repository config:proplist config:update
Chapter 22. Welcome Banner
welcome banner
, edit Fuse install dir/etc/org.apache.karaf.shell.cfg
. Uncomment welcomBanner =
# Specify an additional welcome banner to be displayed when a user logs into the server. # welcomeBanner =
welcomeBanner = \ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ \n\ Hello and welcome to my secure server. \n\ More information here ...\n\ ... \n\ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@\n
Figure 22.1. Log in screen for the Management Console
Chapter 23. Branding JBoss Fuse Console
- Adding a
branding.properties
file toFuse install dir/etc
directoryProcedure 23.1. Adding a
branding.properties
file toFuse install dir/etc
directory- Create a
branding.properties
file with your message. A sample file is given below:{ } welcome = \ \u001B[31m _ ____ ______\u001B[0m\n\ \u001B[31m | | _ \\ | ____| \u001B[0m\n\ \u001B[31m | | |_) | ___ ___ ___ | |__ _ _ ___ ___\u001B[0m\n\ \u001B[31m _ | | _ < / _ \\/ __/ __| | __| | | / __|/ _ \\\u001B[0m\n\ \u001B[31m| |__| | |_) | (_) \\__ \\__ \\ | | | |_| \\__ \\ __/\u001B[0m\n\ \u001B[31m \\____/|____/ \\___/|___/___/ |_| \\__,_|___/\\___|\u001B[0m\n\ \n\ \u001B[1m JBoss Fuse\u001B[0m (6.2.0.redhat-133)\n\ \n\ Open a browser to http://localhost:8181 to access the management console\n\ \n\ Hit '<ctrl-d>' or 'osgi:shutdown' to shutdown JBoss Fuse.\n prompt = \u001B[31mJBossFuse\u001B[0m:\u001B[34m${USER}\u001B[0m\u001B[1m@\u001B[0m\u001B[36m${APPLICATION}\u001B[0m>\u0020 { }
- Copy the
branding.properties
file toFuse install dir/etc
directory. - Navigate to
Fuse install dir/bin
directory. Open the terminal and enter the command./fuse
to start the JBoss Fuse server. You will see your branded message on the JBoss Fuse console.
- Creating a branding bundleAt the startup, JBoss Fuse is looking for a bundle which exports the
org.apache.karaf.branding
package, containing abranding.properties
file. This branding bundle contains a file which stores your customized brand.You can create a simple branding bundle using Maven. Copy yourbranding.properties
file to the maven project resources directory, for example,src/main/resources/org/apache/karaf/branding/
directory. Then using your project'spom.xml
file you can generate the branding bundle as per the steps given below:Procedure 23.2. Creating a branding bundle
- Create
branding.properties
file as shown above. Copy this file to project resources directory, for example,src/main/resources/org/apache/karaf/branding/branding.properties
directory. - A sample
pom.xml
file can be as follows:<?xml version="1.0" encoding="UTF-8"?> <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> <groupId>branding.console</groupId> <artifactId>my.brand</artifactId> <version>1.0-SNAPSHOT</version> <packaging>bundle</packaging> <name>My Brand</name> <build> <plugins> <plugin> <groupId>org.apache.felix</groupId> <artifactId>maven-bundle-plugin</artifactId> <version>2.4.0</version> <extensions>true</extensions> <configuration> <instructions> <Bundle-SymbolicName>manual</bundle-SymbolicName> <Import-Package>*</Import-Package> <Private-Package>!*</Private-Package> <Export-Package> org.apache.karaf.branding </Export-Package> <Spring-Context>*;public-context:=false</Spring-Context> </instructions> </configuration> </plugin> </plugins> </build> </project>
- Open a terminal and navigate to directory where you have saved the
pom.xml
file. Run mvn clean install command to create a branding bundle. - Copy generated branded bundle from the project's
/target
directory toFuse install dir/lib
directory. - In order for JBoss Fuse to use this branding bundle instead of default one, add the following line to
Fuse install dir/etc/custom.properties
file:org.osgi.framework.system.packages.extra = \ org.apache.karaf.branding
- Save your changes. Navigate to
Fuse install dir/bin
directory and run ./fuse to start JBoss Fuse server. You can see your branded console after the startup.
Index
A
- admin commands, Using the admin console commands
B
- broker
- deploying
- standalone container, Standalone containers
- bundle cache, Changing the bundle cache location
C
- child containers, Managing Child Containers
- config shell, Standalone containers
- config.properties, OSGi framework properties, Overview
- config:list, Listing the current configuration
- configuration
- Java Options
- setenv, Setting Java Options
- OSGi, Introducing JBoss Fuse Configuration
F
- fabric:container-stop, Shutting Down a Fabric
- fabric:container-upgrade, Applying a rollup patch, Applying an incremental patch
- fabric:join, Joining a Fabric
- failover, Failover Deployments
- featureRepositories, Modifying the default set of feature URLs
- featuresBoot, Modifying the default installed features
- felix.cache.bufsize, Adjusting the bundle cache buffer
- felix.fileinstall.dir, Specifying the hot deployment folder
- felix.fileinstall.poll, Specifying the scan interval
- felix.fileinstall.tmpdir, Changing the generated-bundle cache location
G
- generated bundle cache, Changing the generated-bundle cache location
H
- hot deployment
- folder, Specifying the hot deployment folder
- monitor interval, Specifying the scan interval
J
- Java Options
- configuration
- setenv, Setting Java Options
- JDBC lock, Using a JDBC Lock System
- JMX configuration
K
- karaf.default.repository, Initial container properties
- karaf.framework, OSGi framework properties
- karaf.framework.felix, OSGi framework properties
- karaf.name, Initial container properties
L
- launching
- client mode, Launching the runtime in client mode
- default mode, Launching the runtime in console mode
- server mode, Launching the runtime in server mode
- lock file, Using a Simple Lock File System
- logging
- commands, Log Commands
O
- org.apache.felix.fileinstall-deploy, Overview
- org.apache.karaf.log, Overview
- org.ops4j.pax.logging, Overview
- org.ops4j.pax.logging.DefaultServiceLog.level, Overview
- org.osgi.framework.storage, Changing the bundle cache location
- org.osgi.framework.storage.clean, Flushing the bundle cache
- org.osgi.service.http.port, Initial container properties
- OSGi
- configuration, Introducing JBoss Fuse Configuration
- OSGi configuration
- creating, Standalone containers
- OSGi framework
- configuring, OSGi framework properties
P
- patch:add, Applying a patch
- patch:install, Applying a patch
- patch:list, Applying a patch, Rolling back a patch
- patch:rollback, Rolling back a patch
- patch:simulate, Applying a patch
- patching
- fabric
- command console, Applying a rollup patch, Applying an incremental patch
- standalone, Applying a patch
- rollback, Rolling back a patch
R
- remote client, Using the remote client
- remote console
- address, Configuring a standalone container for remote access
- container-connect, Using the fabric:container-connect command
- ssh, Using the ssh:ssh console command
- remoteShellLocation, Configuring a standalone container for remote access
- RMI port, Changing the RMI port and JMX URL
- RMI registry
- port number, Changing the RMI port and JMX URL
- rmiRegistryPort, Changing the RMI port and JMX URL
S
- security, Configuring JAAS Security
- serviceUrl, Changing the RMI port and JMX URL
- standalone
- initial features, Configuring the Initial Features in a Standalone Container
- starting, Starting JBoss Fuse
- stopping, Stopping JBoss Fuse
- remote container, Stopping a Remote Container
- system.properties, Initial container properties
Legal Notice
Trademark Disclaimer