This documents the Zab, an atomic broadcast protocol used by ZooKeeper to propagate state changes.

Zab at a high level is a leader based protocol similar to Paxos. Some of the aspects that distinguish Zab from Paxos is that Zab recovers histories rather than single instances of protocols; Zab has prefix ordering properties to allow primary/backup implementations to have multiple outstanding operations outstanding at a time; and Zab does special processing at leadership change to guarantee unique sequence numbers for values proposed by a leader.

The following structures are used for the initial handshake between client and server:

The actual proposals are communicated between follower and leader using a single data structure:

Here are the types of the QuorumPackets:

type

zxid

data

notation

meaning

FOLLOWERINFO(11)

acceptedEpoch

LearnerInfo

FOLLOWERINFO(acceptedEpoch)

The follower has accepted epoch acceptedEpoch.

DIFF(13)

last committed zxid

n/a

DIFF(lastCommittedZxid)

lastCommittedZxid is the last zxid committed by the leader.

TRUNC(14)

truncZxid

n/a

TRUNC(truncZxid)

Truncate the history to truncZxid

SNAP(15)

lastZxid

n/a

SNAP

A state transfer (aka snapshot) will be sent to the follower. this will be a fuzzy state transfer that may include zxids being sent to the follower. The state transfer will immediately follow this packet.

OBSERVERINFO(16)

last zxid learned

LearnerInfo

OBSERVERINFO(lastZxid)

The observer has accepted up to lastZxid.

LEADERINFO(17)

proposed epoch

protocol

LEADERINFO(e)

The new proposed epoch

ACKEPOCH(18)

lastZxid

currentEpoch

ACKEPOCH(lastZxid, currentEpoch)

Acknowledge the acceptance of the new epoch. If the follower has already acknowledged the given epoch, it passes -1 as the currentEpoch to signal that the new epoch is not acknowledged. (We still need to send lastZxid for syncing if necessary)

NEWLEADER(10)

e << 32

n/a

NEWLEADER(e)

Accept this leader as the leader of the epoch e.

UPTODATE(12)

n/a

n/a

UPTODATE

The follower is now uptodate enough to begin serving clients.

PROPOSAL(2)

zxid of proposal

proposed message

PROPOSAL(zxid, data)

Propose a message. (Request that it be accepted into a followers history.)

ACK(3)

zxid of proposal to ack

n/a

ACK(zxid)

Everything sent to the follower by the leader up to zxid has been accepted into its history (logged to disk).

COMMIT(4)

zxid of proposal to commit

n/a

COMMIT(zxid)

Everything in the followers history up to zxid should be committed (aka delivered).

INFORM(8)

zxid of proposal

data of proposal

INFORM(zxid, data)

Deliver the data. (Only used with observers.)

Zab servers have the following state:

Name

Meaning

history

an on disk log of proposals accepted

lastZxid

zxid of the last proposal in the history

acceptedEpoch

the epoch number of the last NEWEPOCH packet accepted

currentEpoch

the epoch number of the last NEWLEADER packet accepted

Implementation assumptions

Implementations must conform to the following:

Use a best-effort leader election algorithm that will elect a leader with the latest history from a quorum of servers.

An observer or follower will only connect to a single leader at a time.

Servers must process packets in the order that they are received. Since TCP maintains ordering when sending packets, this means that packets will be processed in the order defined by the sender.

Leader election

All servers start off looking for a leader. Once the instance of leader election at a given server indicates a leader has emerged it will move to phase 1. If the leader election instance indicates that the server is the leader, it moves to phase 1 as a leader, otherwise it moves to phase 1 as a follower.

Phase 1: Establish an epoch

In this phase an elected leader makes sure that previous leaders cannot commit new proposals and decides on an initial history. (Note a leader is also considered a follower of itself.)

Any failures or timeouts will cause the server to go back to leader election.

l The leader starts accepting connections from followers.

f Followers connect the the leader and send FOLLOWERINFO.

l Once the leader has quorum, it stops accepting connections, and sends LEADERINFO(e) to all followers, where e is greater than all f.acceptedEpoch in the quorum.

f When the follower receives LEADERINFO(e) it will do one of the following:

the followers do not send their histories in the ACK of the NEWEPOCH message.

The leader election protocols that we use try to guarantee that the elected leader has the most up-to-date history from a quorum of processes. They also try to guarantee that there is only one leader elected. It is possible for these guarantees not to hold due to race conditions, stale information, or perhaps even implementation error, so we make sure that the guarantees are satisfied in phase 1. In the tech report we do not assume that the elected leader has the most up-to-date history, so we must find the most up-to-date follower and sync with it. However since the elected leader should be the most up-to-date process, using the leader election protocols that we use, we just check the condition in step 7. If the leader meets the conditions of step 7 we are the most up-to-date, so we have implicitly synced with the most up-to-date process in the quorum. If it doesn't, we go back to leader election.

Another difference from the protocol described in the tech report is the extra information sent in LearnerInfo and the FollowerInfo. The extra information is for implementation purposes: making sure that the protocol version is compatible between client and server, and information for debugging purposes.

Phase 2: Sync with followers

l The leader does the following with each follower connected to it:

adds the follower to the list of connections to send new proposals, so while the server is performing the next steps, it is queuing up any new proposals sent to the follower.

does one of the following:

SNAP if the follower is so far behind that it is better to do a state transfer than send missing transactions.

TRUNC(zxid) if the follower has transactions that the leader has chosen to skip. The leader sets zxid to the last zxid in its history for the epoch of the follower. The leader then sends the transactions that the follower is missing.

DIFF if the leader is sending transactions that the follower is missing. The leader sends missing messages to the follower.

sends a NEWLEADER(e);

The leader releases any queued messages to the follower.

f The follower syncs with the leader, but doesn't modify its state until it receives the NEWLEADER(e) packet. Once it receives NEWLEADER(e) it atomically applies the new state and sets f.currentEpoch = e. It then sends ACK(e << 32).

l Once the leader has received an acknowledgements from a quorum of followers, it takes leadership of epoch e and queues UPTODATE to all followers.

f When a follower receives the UPDATE message, it starts accepting client connections and serving new state.

Phase 3: Broadcast

The leader and followers can have multiple proposals in process and at various stages in the pipeline. The leader will remain active as long as there is a quorum of followers acknowledging its proposals or pings within a timeout interval. The follower will continue to support a leader as long as it receives proposals or pings within a timeout interval. Any failures or timeouts will result in the server going back to leader election.

l the leader queues a packet PROPOSE(zxid, data), where zxid = nextZxid, to all connected followers. It increments nextZxid.

f a follower will log and sync proposals to disk and send ACK(zxid).

l when the leader receives acknowledgements from a quorum of followers it queues COMMIT(zxid) to all followers.