h1. Introduction

h2. Karaf Cellar use cases

The first purpose of Cellar is to synchronize the state of several Karaf instances (named nodes).

It means that all resources modified (installed, started, etc) on one Karaf instance will be propagated to all others
nodes.
Concretely, Cellar will broadcast an event to others nodes when you perform an action.

The nodes list could be discovered (using multicast/unicast), or explicitly defined (using a couple hostname or IP
and port list).

Cellar is able to synchronize:
- bundles (remote, local, or from an OBR)
- config
- features

The second purpose is to provide a Distributed OSGi runtime. It means that using Cellar, you are able to call an OSGi
service located on a remote instance. See the [Transport and DOSGi] section of the user guide.

h2. Cellar network

Cellar relies on Hazelcast (http://www.hazelcast.com), a memory data grid implementation.

You have a full access to the Hazelcast configuration (in etc/hazelcast.xml) allowing you to specify the network
configuration.

Especially, you can enable or not the multicast support and choose the multicast group and port number.

You can also configure on which interface and IP address you configure Cellar and port number used by Cellar:

{code}
    <network>
        <port auto-increment="true">5701</port>
        <join>
            <multicast enabled="true">
                <multicast-group>224.2.2.3</multicast-group>
                <multicast-port>54327</multicast-port>
            </multicast>
            <tcp-ip enabled="false">
                <interface>127.0.0.1</interface>
            </tcp-ip>
            <aws enabled="false">
                <access-key>my-access-key</access-key>
                <secret-key>my-secret-key</secret-key>
                <region>us-east-1</region>
            </aws>
        </join>
        <interfaces enabled="false">
            <interface>10.10.1.*</interface>
        </interfaces>
    </network>
{code}

By default, the Cellar node will start from network port 5701, each new node will use an incremented port number.

h2. Cross topology

!/images/cross_topology.jpg!

This is the default Cellar topology. Cellar is installed on every nodes, each node has the same function.

It means that you can perform actions on any node, it will be broadcasted to all others nodes.

h2. Star topology

!/images/star_topology.jpg!

In this topology, if Cellar is installed on all nodes, you perform actions only on one specific node (the "manager").

To do that, the "manager" is a standard Cellar node, and the event producing is disable on all others nodes
(cluster:producer-stop on all "managed" nodes).

Like this, only the "manager" will send event to the nodes (which are able to consumer and handle), but no event can
be produced on the nodes.