Author: jbonofre
Date: Wed Dec 11 10:13:57 2013
New Revision: 1550096
URL: http://svn.apache.org/r1550096
Log:
[KARAF-2511] Review and update of the failover page of the user guide.
Modified:
karaf/trunk/manual/src/main/webapp/users-guide/failover.conf
Modified: karaf/trunk/manual/src/main/webapp/users-guide/failover.conf
URL:
http://svn.apache.org/viewvc/karaf/trunk/manual/src/main/webapp/users-guide/failover.conf?rev=1550096&r1=1550095&r2=1550096&view=diff
==============================================================================
--- karaf/trunk/manual/src/main/webapp/users-guide/failover.conf (original)
+++ karaf/trunk/manual/src/main/webapp/users-guide/failover.conf Wed Dec 11
10:13:57 2013
@@ -1,34 +1,63 @@
-h1. Failover Deployments
+h1. HA/failover and cluster
-Karaf provides failover capability using either a simple lock file or a JDBC
locking mechanism. In both cases, a container-level lock system allows bundles
to be preloaded into the slave Karaf instance in order to provide faster
failover performance.
+Apache Karaf natively provides a failover mechanism. It uses a kind of
master/slave topology where one instance is active
+and the others are in standby.
-h2. Simple lock file
+If you are looking for cluster of Apache Karaf instances (active/active),
[Apache Karaf Cellar|http://karaf.apache.org/index/subprojects/cellar.html] is
a solution.
-The simple lock file mechanism is intended for failover configurations where
instances reside on the same host machine or share a file system with lock
support.
+Karaf provides failover capability using either a simple lock file or a JDBC
locking mechanism.
+In both cases, a container-level lock system allows bundles to be preloaded
into the slave Karaf instance in order to provide faster failover performance.
-To use this feature, edit the {{$KARAF_HOME/etc/system.properties}} file as
follows on each system in the master/slave setup:
+h2. HA/failover (active/passive)
-{noformat}
+The Apache Karaf failover capability uses a lock system.
+
+This container-level lock system allows bundles installed on the master to be
preloaded on the slave, in order to provide faster failover performance.
+
+Two types of lock are supported:
+
+* filesystem lock
+* database lock
+
+When a first instance starts, if the lock is available, it takes the lock and
become the master.
+If a second instance starts, it tries to acquire the lock. As the lock is
already hold by the master, the instance becomes
+a slave, in standby mode (not active). A slave periodically check if the lock
has been released or not.
+
+h3. Filesystem lock
+
+The Apache Karaf instances share a lock on the filesystem. It means that the
filesystem storing the lock has to be accessible
+to the different instances (using SAN, NFS, ...).
+
+The configuration of the lock system has to be defined in the
{{etc/system.properties}} file, on each instance (master/slave):
+
+{code}
karaf.lock=true
karaf.lock.class=org.apache.karaf.main.SimpleFileLock
karaf.lock.dir=<PathToLockFileDirectory>
karaf.lock.delay=10
-{noformat}
+{code}
+
+* {{karaf.lock}} property enables the the HA/failover mechanism
+* {{karaf.lock.class}} property contains the class name providing the lock
implementation. Here, we use the filesystem lock.
+* {{karaf.lock.dir}} property contains the location where the lock will be
written. All instances have to share the same lock.
+* {{karaf.lock.delay}} property is the interval period (in seconds) to check
if the lock has been released or not.
-*Note*: Ensure that the {{karaf.lock.dir}} property points to the same
directory for both the master and slave instance, so that the slave can acquire
the lock only when the master releases it.
+h3. Database lock
+It's not always possible and easy to have a shared filesystem between multiple
Apache Karaf instances.
-h2. JDBC locking
+Instead of sharing a filesystem, Apache Karaf supports sharing a database.
-The JDBC locking mechanism is intended for failover configurations where
instances exist on separate machines. In this deployment, the master instance
holds a lock on a Karaf locking table hosted on a database. If the master loses
the lock, a waiting slave process gains access to the locking table and fully
starts its container.
+The master instance holds the lock by locking a table in the database. If the
master loses the lock, a waiting slave
+gains access to the locking table, acquire the lock on the table and starts.
-To use this feature, do the following on each system in the master/slave setup:
+The database lock uses JDBC (Java DataBase Connectivity). To use database
locking, you have to:
-* Update the classpath to include the JDBC driver
-* Update the {{$KARAF_HOME/bin/karaf}} script to have a unique JMX remote port
set if instances reside on the same host
-* Update the {{$KARAF_HOME/etc/system.properties}} file as follows:
+* copy the JDBC driver in the {{lib/ext}} folder on each instance. The JDBC
driver to use is the one corresponding to the
+ database used for the locking system.
+* update {{etc/system.properties}} file on each instance:
-{noformat}
+{code}
karaf.lock=true
karaf.lock.class=org.apache.karaf.main.DefaultJDBCLock
karaf.lock.level=50
@@ -40,23 +69,38 @@ karaf.lock.jdbc.password=password
karaf.lock.jdbc.table=KARAF_LOCK
karaf.lock.jdbc.clustername=karaf
karaf.lock.jdbc.timeout=30
-{noformat}
-
-*Note*:
-
-* This process will fail if a JDBC driver is not on the classpath.
-* The "sample" database referred to above will be created if it does not exist.
-* The first Karaf instance to acquire the locking table is the master instance.
-* If the connection to the database is lost, the master instance tries to
gracefully shutdown, allowing a slave instance to become master when the
database service is restored. The former master will require a manual restart.
-* For 2.2.x, 2.3.x, 3.0.x you need to rename the database Driver jar to prefix
with 'karaf-' in order for karaf to pick it up, otherwise you will see karaf
just hang on startup and the log will show you that it could not find the
driver.
+{code}
-h3. JDBC locking on Oracle
+* {{karaf.lock}} property enabled the HA/failover mechanism
+* {{karaf.lock.class}} property contains the class name providing the lock
implementation. The {{org.apache.karaf.main.DefaultJDBCLock}}
+ is the most generic database lock system implementation. Apache Karaf
supports lock system for specific databases (see later for details).
+* {{karaf.lock.level}} property is the container-level locking (see later for
details).
+* {{karaf.lock.delay}} property is the interval period (in seconds) to check
if the lock has been released or not.
+* {{karaf.lock.jdbc.url}} property contains the JDBC URL to the database
(derby in this example).
+* {{karaf.lock.jdbc.driver}} property contains the class name of the JDBC
driver to use (derby in this example).
+* {{karaf.lock.jdbc.user}} property contains the username to use to connect to
the database.
+* {{karaf.lock.jdbc.password}} property contains the password to use to connet
to the database.
+* {{karaf.lock.jdbc.table}} property contains the database table to use for
the lock.
+
+{warning}
+Apache Karaf won't start if the JDBC driver is not present in the {{lib/ext}}
folder. In order to be loaded correctly,
+the JDBC driver jar file has to be prefixed with {{karaf-}} (for instance the
{{ojdbc14.jar}} has to be renamed as {{karaf-ojdbc14.jar}} in the {{lib/ext}}
folder.
+{warning}
+
+{warning}
+The {{sample}} database will be created automatically if it does not exist.
+{warning}
+
+{warning}
+If the connection to the database is lost, the master instance tries to
gracefully shutdown, allowing a slave instance to
+become the master when the database is back. The former master instance will
required a manual restart.
+{warning}
-If you are using Oracle as your database for JDBC locking, the
{{karaf.lock.class}} property in the {{$KARAF_HOME/etc/system.properties}} file
must point to {{org.apache.karaf.main.OracleJDBCLock}}.
+h4. Lock on Oracle
-Otherwise, configure the system.properties file as normal for your setup, for
example:
+Apache Karaf supports Oracle database for locking. The lock implementation
class name to use is {{org.apache.karaf.main.lock.OracleJDBCLock}}:
-{noformat}
+{code}
karaf.lock=true
karaf.lock.class=org.apache.karaf.main.lock.OracleJDBCLock
karaf.lock.jdbc.url=jdbc:oracle:thin:@hostname:1521:XE
@@ -66,19 +110,20 @@ karaf.lock.jdbc.password=password
karaf.lock.jdbc.table=KARAF_LOCK
karaf.lock.jdbc.clustername=karaf
karaf.lock.jdbc.timeout=30
-{noformat}
+{code}
-As with the default JDBC locking setup, the Oracle JDBC driver JAR file must
be in your classpath. You can ensure this by copying the {{ojdbc14.jar}} into
Karaf's {{lib}} folder before starting Karaf.
+The {{ojdbc*.jar}} JDBC driver file has to be copied as
{{lib/ext/karaf-ojdbc*.jar}}.
-*Note*: The {{karaf.lock.jdbc.url}} requires an active SID, which means you
must manually create a database instance before using this particular lock.
+{warning}
+The {{karaf.lock.jdbc.url}} property contains a JDBC URL which requires an
active SID. It means that you must manually create the Oracle
+database instance first before using the lock mechanism.
+{warning}
-h3. Derby
+h4. Lock on Derby
-The same rules apply when using derby. Make sure you have the driver jar file
in the Karaf {{lib}} folder before starting Karaf.
+Apache Karaf supports Apache Derby database for locking. The lock
implementation class name to use is
{{org.apache.karaf.main.lock.DerbyJDBCLock}}:
-Then make you update the properties in {{$KARAF_HOME/etc/system.properties}}
to look something like this example:
-
-{noformat}
+{code}
karaf.lock=true
karaf.lock.class=org.apache.karaf.main.lock.DerbyJDBCLock
karaf.lock.jdbc.url=jdbc:derby://127.0.0.1:1527/dbname
@@ -88,15 +133,15 @@ karaf.lock.jdbc.password=password
karaf.lock.jdbc.table=KARAF_LOCK
karaf.lock.jdbc.clustername=karaf
karaf.lock.jdbc.timeout=30
-{noformat}
+{code}
-h3. MySQL
+The Derby JDBC driver file name has to be copied in the {{lib/ext}} folder
with the {{karaf-}} prefix.
-Make sure you have the MySQL driver jar file in the Karaf {{lib}} folder
before starting Karaf.
+h4.Lock on MySQL
-Then make you update the properties in {{$KARAF_HOME/etc/system.properties}}
to look something like this example:
+Apache Karaf supports MySQL database for locking. The lock implementation
class name to use is {{org.apache.karaf.main.lock.MySQLJDBCLock}}:
-{noformat}
+{code}
karaf.lock=true
karaf.lock.class=org.apache.karaf.main.lock.MySQLJDBCLock
karaf.lock.jdbc.url=jdbc:mysql://127.0.0.1:3306/dbname
@@ -106,15 +151,15 @@ karaf.lock.jdbc.password=password
karaf.lock.jdbc.table=KARAF_LOCK
karaf.lock.jdbc.clustername=karaf
karaf.lock.jdbc.timeout=30
-{noformat}
+{code}
-h3. PostgreSQL
+The MySQL JDBC driver file name has to be copied in {{lib/ext}} folder with
the {{karaf-}} prefix.
-Make sure you have the PostgreSQL driver jar file in the Karaf {{lib}} folder
before starting Karaf.
+h4. Lock on PostgreSQL
-Then make you update the properties in {{$KARAF_HOME/etc/system.properties}}
to look something like this example:
+Apache Karaf supports PostgreSQL database for locking. The lock implementation
class name to use is {{org.apache.karaf.main.lock.PostgreSQLJDBCLock}}:
-{noformat}
+{code}
karaf.lock=true
karaf.lock.class=org.apache.karaf.main.lock.PostgreSQLJDBCLock
karaf.lock.jdbc.url=jdbc:postgresql://127.0.0.1:1527/dbname
@@ -124,35 +169,62 @@ karaf.lock.jdbc.password=password
karaf.lock.jdbc.table=KARAF_LOCK
karaf.lock.jdbc.clustername=karaf
karaf.lock.jdbc.timeout=0
-{noformat}
-
-
-{anchor:locklevel}
+{code}
-h2. Container-level locking
+The PostgreSQL JDBC driver file has to be copied in the {{lib/ext}} folder
with the {{karaf-}} prefix.
-Container-level locking allows bundles to be preloaded into the slave kernel
instance in order to provide faster failover performance. Container-level
locking is supported in both the simple file and JDBC locking mechanisms.
+h4. Lock on Microsoft SQLServer
-To implement container-level locking, add the following to the
{{$KARAF_HOME/etc/system.properties}} file on each system in the master/slave
setup:
+Apache Karaf supports Microsoft SQLServer database for locking. The lock
implementation class name to use is
{{org.apache.karaf.main.lock.SQLServerJDBCLock}}:
-{noformat}
+{code}
karaf.lock=true
+karaf.lock.class=org.apache.karaf.main.lock.SQLServerJDBCLock
karaf.lock.level=50
karaf.lock.delay=10
-{noformat}
+karaf.lock.jdbc.url=jdbc:jtds:sqlserver://127.0.0.1;databaseName=sample
+karaf.lock.jdbc.driver=net.sourceforge.jtds.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
+{code}
+
+The JTDS JDBC driver file has to be copied in the {{lib/ext}} folder with the
{{karaf-}} prefix.
+
+h3. Container-level locking
-The {{karaf.lock.level}} property tells the Karaf instance how far up the boot
process to bring the OSGi container. All bundles with an ID equals or lower to
this start level will be started in that Karaf instance.
+Apache Karaf supports container-level locking. It allows bundles to be
preloaded into the slave instance.
+Thanks to that, switching to a slave instance is very fast as the slave
instance already contains all required bundles.
-Bundle start levels are specified in {{$KARAF_HOME/etc/startup.properties}},
in the format {{jar.name=level}}. The core system bundles have levels below 50,
while user bundles have levels greater than 50.
+The container-level locking is supported in both filesystem and database lock
mechanisms.
+
+The container-level locking uses the {{karaf.lock.level}} property:
+
+{code}
+karaf.lock.level=80
+{code}
+
+The {{karaf.lock.level}} property tells the Karaf instance how far up the boot
process to bring the OSGi container.
+All bundles with an ID equals or lower to this start level will be started in
that Karaf instance.
+
+As reminder, the bundles start levels are specified in
{{etc/startup.properties}}, in the {{url=level}} format.
|| 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 end up being
started. |
+| <80 | 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. |
+| >80 | This setting is not recommended as user bundles will end up being
started. |
+
+{warning}
+Using 'hot' standby means that the slave instances are running and bind some
ports. So, if you use master and slave instances on the same machine, you have
+to update the slave configuration to bind the services (ssh, JMX, etc) on
different port numbers.
+{warning}
+
+h2. Cluster (active/active)
-*Note*: When using a 'hot' spare on the same host you need to set the JMX
remote port to a unique value to avoid bind conflicts. You can edit the Karaf
start script to include the following:
+Apache Karaf doesn't natively support cluster. By cluster, we mean several
active instances, synchronized with each other.
-{noformat}
-DEFAULT_JAVA_OPTS="-server $DEFAULT_JAVA_OPTS
-Dcom.sun.management.jmxremote.port=1100
-Dcom.sun.management.jmxremote.authenticate=false"
-{noformat}
+However, [Apache Karaf
Cellar|http://karaf.apache.org/index/subprojects/cellar.html] can be installed
to provide cluster support.
+See the [Apache Karaf Cellar
website|http://karaf.apache.org/index/subprojects/cellar.html] for details.
\ No newline at end of file
