---
layout: "docs"
page_title: "Serf Protocol Compatibility Promise"
sidebar_current: "docs-upgrading-compatibility"
description: |-
We expect Serf to run in large clusters as long-running agents. Because
upgrading agents in this sort of environment relies heavily on protocol
compatibility, this page makes it clear on our promise to keeping different
Serf versions compatible with each other.
We promise that every subsequent release of Serf will remain backwards
compatible with at least one prior version. Concretely: version 0.5 can
speak to 0.4 (and vice versa), but may not be able to speak to 0.1.
The backwards compatibility must be explicitly enabled: Serf agents by
default will speak the latest protocol, but can be configured to speak earlier
ones. If speaking an earlier protocol, new features may not be available.
The ability for an agent to speak an earlier protocol is only so that they
can be upgraded without cluster disruption.
This compatibility guarantee makes it possible to upgrade Serf agents one
at a time, one version at a time. For more details on the specifics of
upgrading, see the upgrading page.
| Version | Protocol Compatibility |
|---|---|
| 0.1 | 0 |
| 0.2 | 0, 1 |
| 0.3 | 0, 1, 2 see warning below |
| 0.4 | 1, 2, 3 see warning below |
| 0.5 | 2, 3, 4 see warning below |
| 0.6 | 2, 3, 4 see warning below |
~> Warning! Version 0.3 introduces support for dynamic ports, allowing each
agent to bind to a different port. However, this feature is only supported
if all agents are running protocol version 2. Due to the nature of this
feature, it is hard to detect using the versioning scheme. If ports are kept
consistent across the cluster, then protocol version 2 is fully backwards
compatible.
~> Warning! Version 0.4 introduces support for dynamic tags, allowing each
agent to provide key/value tags and update them without restarting. This feature is only supported
if all agents are running protocol version 3. If an agent is running an older protocol,
then only the "role" tag is supported for backwards compatibility.
~> Warning! Version 0.6 introduces support for key rotation. This feature
uses the same protocol version, but requires that all agents be on 0.6. Unless this condition
is met, attempting to use key rotation will result in errors.
