You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@karaf.apache.org by jb...@apache.org on 2013/12/11 11:13:57 UTC
svn commit: r1550096 -
/karaf/trunk/manual/src/main/webapp/users-guide/failover.conf
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