karaf-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jbono...@apache.org
Subject svn commit: r1550096 - /karaf/trunk/manual/src/main/webapp/users-guide/failover.conf
Date Wed, 11 Dec 2013 10:13:57 GMT
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



Mime
View raw message