[[ap-recent-changes]]
[appendix]
== Recent changes

This appendix is for users who upgrade from earlier DRBD versions to
DRBD 8.4. It highlights some important changes to DRBD's configuration
and behavior.

[[s-recent-changes-volumes]]
=== Volumes

Volumes are a new concept in DRBD 8.4. Prior to 8.4, every resource
had only one block device associated with it, thus there was a
one-to-one relationship between DRBD devices and resources. Since 8.4,
multiple volumes (each corresponding to one block device) may share a
single replication connection, which in turn corresponds to a single
resource.

[[s-recent-changes-volumes-udev]]
==== Changes to udev symlinks

The DRBD udev integration scripts manage symlinks pointing to
individual block device nodes. These exist in the +/dev/drbd/by-res+
and +/dev/drbd/by-disk+ directories.

In DRBD 8.3 and earlier, links in +/dev/drbd/by-disk+ point to single
block devices:

.udev managed DRBD symlinks in DRBD 8.3 and earlier
----------------------------
lrwxrwxrwx 1 root root 11 2011-05-19 11:46 /dev/drbd/by-res/home ->
  ../../drbd0
lrwxrwxrwx 1 root root 11 2011-05-19 11:46 /dev/drbd/by-res/data ->
  ../../drbd1
lrwxrwxrwx 1 root root 11 2011-05-19 11:46 /dev/drbd/by-res/nfs-root ->
  ../../drbd2
----------------------------

In DRBD 8.4, since a single resource may correspond to multiple
volumes, +/dev/drbd/by-res/<resource>+ becomes a _directory_,
containing symlinks pointing to individual volumes:

.udev managed DRBD symlinks in DRBD 8.4
----------------------------
lrwxrwxrwx 1 root root 11 2011-07-04 09:22 /dev/drbd/by-res/home/0 ->
  ../../drbd0
lrwxrwxrwx 1 root root 11 2011-07-04 09:22 /dev/drbd/by-res/data/0 ->
  ../../drbd1
lrwxrwxrwx 1 root root 11 2011-07-04 09:22 /dev/drbd/by-res/nfs-root/0 ->
  ../../drbd2
lrwxrwxrwx 1 root root 11 2011-07-04 09:22 /dev/drbd/by-res/nfs-root/1 ->
   ../../drbd3
----------------------------

Configurations where filesystems are referred to by symlink must be
updated when moving to DRBD 8.4, usually by simply appending +/0+ to
the symlink path.

[[s-recent-changes-config]]
=== Changes to the configuration syntax

This section highlights changes to the configuration syntax. It
affects the DRBD configuration files in +/etc/drbd.d+, and
+/etc/drbd.conf+.

IMPORTANT: The +drbdadm+ parser still accepts pre-8.4 configuration
syntax and automatically translates, internally, into the current
syntax. Unless you are planning to use new features not present in
prior DRBD releases, there is no requirement to modify your
configuration to the current syntax. It is, however, recommended that
you eventually adopt the new syntax, as the old format will no longer
be supported in DRBD 9.

[[s-recent-changes-config-booleans]]
==== Boolean configuration options

+drbd.conf+ supports a variety of boolean configuration options. In
pre DRBD 8.4 syntax, these boolean options would be set as follows:

.Pre-DRBD 8.4 configuration example with boolean options
[source,drbd]
----------------------------
resource test {
  disk {
    no-md-flushes;
  }
}
----------------------------

This led to configuration issues if you wanted to set a boolean
variable in the +common+ configuration section, and then override it
for individual resources:

.Pre-DRBD 8.4 configuration example with boolean options in +common+ section
[source,drbd]
----------------------------
common {
  no-md-flushes;
}
resource test {
  disk {
    # No facility to enable disk flushes previously disabled in
    # "common"
  }
}
----------------------------

In DRBD 8.4, all boolean options take a value of +yes+ or +no+, making
them easily configurable both from +common+ and from individual
+resource+ sections:

.DRBD 8.4 configuration example with boolean options in +common+ section
[source,drbd]
----------------------------
common {
  md-flushes no;
}
resource test {
  disk {
    md-flushes yes;
  }
}
----------------------------

[[s-recent-changes-config-syncer]]
==== +syncer+ section no longer exists

Prior to DRBD 8.4, the configuration syntax allowed for a +syncer+
section which has become obsolete in 8.4. All previously existing
+syncer+ options have now moved into the +net+ or +disk+ sections of
resources.

.Pre-DRBD 8.4 configuration example with +syncer+ section
[source,drbd]
----------------------------
resource test {
  syncer {
    al-extents 3389;
    verify-alg md5;
  }
  ...
}
----------------------------

The above example is expressed, in DRBD 8.4 syntax, as follows:

.DRBD 8.4 configuration example with +syncer+ section replaced
[source,drbd]
----------------------------
resource test {
  disk {
    al-extents 3389;
  }
  net {
    verify-alg md5;
  }
  ...
}
----------------------------

[[s-recent-changes-config-protocol]]
==== +protocol+ option is no longer special

In prior DRBD releases, the +protocol+ option was awkwardly (and
counter-intuitively) required to be specified on its own, rather than
as part of the +net+ section. DRBD 8.4 removes this anomaly:

.Pre-DRBD 8.4 configuration example with standalone +protocol+ option
[source,drbd]
----------------------------
resource test {
  protocol C;
  ...
  net {
    ...
  }
  ...
}
----------------------------

The equivalent DRBD 8.4 configuration syntax is:

.DRBD 8.4 configuration example with +protocol+ option within +net+ section
[source,drbd]
----------------------------
resource test {
  net {
    protocol C;
    ...
  }
  ...
}
----------------------------


[[s-recent-changes-config-options]]
==== New per-resource +options+ section

DRBD 8.4 introduces a new +options+ section that may be specified
either in a +resource+ or in the +common+ section. The +cpu-mask+
option has moved into this section from the +syncer+ section in which
it was awkwardly configured before. The +on-no-data-accessible+ option
has also moved to this section, rather than being in +disk+ where
it had been in pre-8.4 releases.

.Pre-DRBD 8.4 configuration example with +cpu-mask+ and +on-no-data-accessible+
[source,drbd]
----------------------------
resource test {
  syncer {
    cpu-mask ff;
  }
  disk {
    on-no-data-accessible suspend-io;
  }
  ...
}
----------------------------

The equivalent DRBD 8.4 configuration syntax is:

.Pre-DRBD 8.4 configuration example with +options+ section
[source,drbd]
----------------------------
resource test {
  options {
    cpu-mask ff;
    on-no-data-accessible suspend-io;
  }
  ...
}
----------------------------


[[s-recent-changes-net]]
=== On-line changes to network communications

[[s-recent-changes-change-protocol]]
==== Changing the replication protocol

Prior to DRBD 8.4, changes to the replication protocol were impossible
while the resource was on-line and active. You would have to change
the +protocol+ option in your resource configuration file, then issue
+drbdadm disconnect+ and finally +drbdadm connect+ on both nodes.

In DRBD 8.4, the replication protocol can be changed on the fly. You
may, for example, temporarily switch a connection to asynchronous
replication from its normal, synchronous replication mode.

.Changing replication protocol while connection is established
----------------------------
drbdadm net-options --protocol=A <resource>
----------------------------

[[s-recent-changes-switch-dual-primary]]
==== Changing from single-Primary to dual-Primary replication

Prior to DRBD 8.4, it was impossible to switch between single-Primary
to dual-Primary or back while the resource was on-line and active. You
would have to change the +allow-two-primaries+ option in your resource
configuration file, then issue +drbdadm disconnect+ and finally
+drbdadm connect+ on both nodes.

In DRBD 8.4, it is possible to switch modes on-line.

CAUTION: It is _required_ for an application using DRBD dual-Primary
mode to use a clustered file system or some other distributed locking
mechanism. This applies regardless of whether dual-Primary mode is
enabled on a temporary or permanent basis.

Refer to <<s-enable-dual-primary-temporary>> for switching to
dual-Primary mode while the resource is on-line.


[[s-recent-changes-drbdadm]]
=== Changes to the +drbdadm+ command

[[s-recent-changes-drbdadm-passthrough-options]]
==== Changes to pass-through options

Prior to DRBD 8.4, if you wanted +drbdadm+ to pass special options through to
+drbdsetup+, you had to use the arcane +--{nbsp}--<option>+ syntax, as in the
following example:

.Pre-DRBD 8.4 +drbdadm+ pass-through options
----------------------------
drbdadm -- --discard-my-data connect <resource>
----------------------------

Instead, +drbdadm+ now accepts those pass-through options as normal options:

.DRBD 8.4 +drbdadm+ pass-through options
----------------------------
drbdadm connect --discard-my-data <resource>
----------------------------

NOTE: The old syntax is still supported, but its use is strongly
discouraged. However, if you choose to use the new, more
straightforward syntax, you must specify the option
(+--discard-my-data+) _after_ the subcommand (+connect+) and _before_
the resource identifier.

[[s-recent-changes-drbdadm-force]]
==== +--force+ option replaces +--overwrite-data-of-peer+

The +--overwrite-data-of-peer+ option is no longer present in DRBD
8.4. It has been replaced by the simpler +--force+. Thus, to kick off
an initial resource synchronization, you no longer use the following
command:

.Pre-DRBD 8.4 initial sync +drbdadm+ commands
----------------------------
drbdadm -- --overwrite-data-of-peer primary <resource>
----------------------------

Use the command below instead:

.DRBD 8.4 initial sync +drbdadm+ commands
----------------------------
drbdadm primary --force <resource>
----------------------------


[[s-recent-changes-defaults]]
=== Changed default values

In DRBD 8.4, several +drbd.conf+ default values have been updated to
match improvements in the Linux kernel and available server hardware.

[[s-recent-changes-defaults-al-extents]]
==== Number of concurrently active Activity Log extents (+al-extents+)

+al-extents+' previous default of 127 has changed to 1237, allowing
for better performance by reducing the amount of metadata disk write
operations. The associated extended resynchronization time after a
primary node crash, which this change introduces, is marginal given
the ubiquity of Gigabit Ethernet and higher-bandwidth replication
links.

[[s-recent-changes-defaults-use-rle]]
==== Run-length encoding (+use-rle+)

Run-length encoding (RLE) for bitmap transfers is enabled by default
in DRBD 8.4; the default for the +use-rle+ option is +yes+. RLE
greatly reduces the amount of data transferred during the
<<s-quick-sync-bitmap,quick-sync bitmap>> exchange (which occurs any
time two disconnected nodes reconnect).

[[s-recent-changes-on-io-error]]
==== I/O error handling strategy (+on-io-error+)

DRBD 8.4 defaults to <<fp-io-error-detach,masking I/O errors>>, which
replaces the earlier behavior of <<fp-io-error-pass-on,passing them on>>
to upper layers in the I/O stack. This means that a DRBD volume
operating on a faulty drive automatically switches to the +Diskless+
disk state and continues to serve data from its peer node.

[[s-recent-changes-defaults-variable-rate-sync]]
==== Variable-rate synchronization

<<s-variable-rate-sync,Variable-rate synchronization>> is on by
default in DRBD 8.4. The default settings are equivalent to the
following configuration options:

.DRBD 8.4 default options for variable-rate synchronization
[source,drbd]
----------------------------
resource test {
  disk {
    c-plan-ahead 20;
    c-fill-target 50k;
    c-min-rate 250k;
  }
  ...
----------------------------

[[s-recent-changes-defaults-minor-count]]
==== Number of configurable DRBD devices (+minor-count+)

The maximum number of configurable DRBD devices (previously 255) is
1,048,576 (2^20^) in DRBD 8.4. This is more of a theoretical limit
that is unlikely to be reached in production systems.
