ddsnap

Section: Maintenance Commands (8)
Updated: Nov 30, 2007
Index Return to Main Contents

NAME

ddsnap - block device snapshot and replication

SYNOPSIS

ddsnap [-V|--version] [-?|--help] [--usage] subcommand [option...] [operand...]
ddsnap initialize [-y|--yes] [-j|--journalsize journalsize] [-b|--blocksize blocksize] [-c|--chunksize chunksize] [-k|--cachesize cachesize] snapshot_device origin_device [meta_device]
ddsnap agent [-f|--foreground] [-l|--logfile file_name] [-p|--pidfile file_name] agent_socket
ddsnap server [-f|--foreground] [-l|--logfile file_name] [-p|--pidfile file_name] snapshot_device origin_device [dev/meta] agent_socket server_socket
ddsnap create socket_name snapshot
ddsnap delete socket_name snapshot
ddsnap list socket_name
ddsnap priority socket_name snap_tag new_priority_value
ddsnap usecount socket_name snap_tag [diff_amount]
ddsnap resize socket_name [-o|--origin newsize] [-s|--snapshot newsize] [-m|--metadata newsize]
ddsnap status [-v|--verbose] socket_name [snapshot]

ddsnap delta changelist socket_name changelist_name snapshot1 snapshot2
ddsnap delta create [-o|--overwrite] [-d|--difference] [-b|--best] [-z|--zip compression_level] changelist deltafile_name snapshot_device_stem
ddsnap delta apply deltafile_name snapshot_device_stem
ddsnap transmit [-o|--overwrite] [-d|--difference] [-b|--best] [-z|--zip compression_level] [-p|--progress progress_file] socket_name host[:port] [fromsnap] tosnap
ddsnap delta listen [-f|--foreground] [-l|--logfile file_name] [-p|--pidfile file_name] snapshot_device_stem [host[:port]]

DESCRIPTION

ddsnap provides block device replication given a block level snapshot facility capable of holding multiple simultaneous snapshots efficiently. ddsnap can generate a list of snapshot chunks that differ between two snapshots, then send that difference over the wire. On a downstream server, write the updated data to a snapshotted block device.

ddsnap snapshots a block device and replicates the data on another block device. It is assumed that the user has access to hardware capable of holding multiple simultaneous snapshots efficiently. ddsnap can also general a list of snapshot chunks containing the differences between two snapshots and can send those chunks across a network. On the target server, ddsnap writes the updated data to a block device.

ddsnap provides some useful low-level flexibility. The user can set it to run daemonized or in the foreground; can set the desired journal size to use when creating the snapshot, and can set the desired block size on the target block device.

OPTIONS

-y|--yes: Answers yes to all prompts.
-j journalsize|--journalsize=journalsize: Specifies the journal size, i.e. 200k. Defaults to 400k.
-b blocksize|--blocksize=blocksize: Specifies the block size. Input has to be a power of two, i.e. 8k. Defaults to chunksize.
-b cachesize|--cachesize=cachesize: Specifies the amount of RAM to dedicate to the snapshot btree cache. If not specified or if specified as 0 (zero), defaults to min(128MB, system ram size/4).
-f|--foreground: Sets the server to run in the foreground. The default is to run daemonized.
-l file_name|--logfile=file_name: Specifies the log file.
-p file_name|--pidfile=file_name: Specifies the preferred process id file.
-v|--verbose: Gives lots of information about what's happening.
-o|--overwrite: The delta file contains the literal contents of each destination snapshot chunk from the difference list. Generating a delta this way only requires reading one snapshot volume and applying it to the destination volume does not require any reading at all, so this method is very fast. However, the delta file can be quite large.
-d|--difference: Generates a delta file using xdelta binary differencing. The chunk level delta is compressed by taking a binary difference between source and destination chunks and compressing the result via the xdelta algorithm.
-b|--best: Generates a delta file by trying both binary differencing and straight compression methods, choosing the best method for each extent of the output delta. Uses more CPU and disk bandwidth in return for slightly smaller delta files. This option overrides the -o and -d options.
-z compression_level|--zip=compression_level: Specifies a zlib or xdelta compression level from 0 to 9, where level 0 is no compression and level 9 is maximum compression. If unspecified, compression level defaults to 6.
-V|--version: Shows version.
-?|--help: Prints a short help message and exits.
--usage: prints a short usage message and exits.

COMMANDS

initialize: [-y|--yes] [-j|--journalsize journalsize] [-b|--blocksize blocksize] [-c|--chunksize chunksize] snapshot_device origin_device [meta_device]
Initializes snapshot storage device.
agent: [-f|--foreground] [-l|--logfile file_name] [-p|--pidfile file_name] agent_socket
Starts the snapshot agent.
server: [-f|--foreground] [-l|--logfile file_name] [-p|--pidfile file_name] snapshot_device origin_device [dev/meta] agent_socket server_socket
Starts the snapshot server.
create: socket_name snapshot
Creates a snapshot with the given sockname and snapshot.
delete: socket_name snapshot
Deletes a snapshot with the given sockname and snapshot.
list: socket_name
Returns a list of snapshots currently held.
priority: socket_name snap_tag new_priority_value
Sets the priority of the snapshot with the given sockname and snap_tag to the given priority_value.
usecount: socket_name snap_tag [diff_amount]
Changes the use count of the snapshot with the given sockname and snap_tag by adding diff_amount to current snapshot usecount. If diff_amount is omitted, 0 is assumed.
resize: socket_name [-o|--origin newsize] [-s|--snapshot newsize] [-m|--metadata newsize]
Resize the origin/snapshot/metadata device of an existing ddsnap volume.
status: [-v|--verbose] socket_name [snapshot]
Reports snapshot usage statistics.
delta changelist: socket_name changelist_name snapshot1 snapshot2
Creates a changelist from snapshot1 and snapshot2 with the given changelist_name.
delta create: [-o|--overwrite] [-d|--difference] [-b|--best] [-z|--zip compression_level] changelist_name deltafile_name snapshot_device_stem
Creates a deltafile from the given changelist and snapshot device stem with the given deltafile_name. Defaults to optimal mode if no option was selected.
delta apply: deltafile_name snapshot_device_stem
Applies the deltafile to the given device.
transmit: [-o|--overwrite] [-d|--difference] [-b|--best] [-z|--zip compression_level] socket_name host[:port] [fromsnap] tosnap
Streams a delta from snapshot fromsnap to snapshot tosnap to downstream server host. If fromsnap is omitted, the full volume, as it existed at tosnap is sent. If progress_file is specified, it is updated once a second with replication progress data.
delta listen: [-f|--foreground] [-l|--logfile string] [-p|--pidfile string] snapshot_device_stem [host[:port]]
Listens for a deltafile arriving from upstream.

EXAMPLES

# Initializing snapshot storage device

sudo ./ddsnap initialize /dev/test-snapstore /dev/test-origin

# Start up the agent server

sudo ./ddsnap agent /tmp/control

# Start up the snapshot server

sudo ./ddsnap server /dev/test-snapstore /dev/test-origin /tmp/control /tmp/server

# Creating a snapshot

sudo ./ddsnap create /tmp/server 0

# Creating a changelist named changelist0-1 given /tmp/server and two snapshots (0 and 1)

sudo ./ddsnap delta changelist /tmp/server changelist0-1 0 1

# Creating a deltafile named deltafile0-1 based on changelist0-1, /dev/mapper/snapshot(0) and /dev/mapper/snapshot(1) in raw mode

sudo ./ddsnap delta create -o changelist0-1 deltafile0-1 /dev/mapper/snapshot

# Applying a deltafile name deltafile0-1 to a device named /dev/mapper/vol

sudo ./ddsnap delta apply /path/to/deltafile0-1 /dev/mapper/vol

TERMINOLOGY

snapshot - a virtually instant copy of a defined collection of data created at a particular instant in time.
origin volume - One of two block devices underlying a virtual snapshot device. This volume is mapped one-to-one to a snapshot origin virtual device. The virtual device could be removed and the underlying origin volume accessed directly, at the risk of losing the integrity of any snapshots sharing data with the origin.
snapshot store - The other block device underlying a virtual snapshot device. This volume contains data chunks that were copied from the origin in order to preserve the integrity of snapshot data, or were written directly to the snapshot store via a snapshot virtual device. It also contains all metadata required to keep track of which snapshot store chunks belong to which snapshots.
chunk - a user-definable binary multiple of 4K block size.
exception - a chunk of data in the snapshot store, belonging to one or more snapshots.

FUTURE ADDITIONS

In the future, we will go further in the direction of hiding the device names, by coming up with a proper library API for creating the virtual devices so we don't need the clumsy dmsetup command any more or the even more clumsy libdevmapper interface, or worse yet, the devmapper ioctl interface. Our library interface might even offer the option of creating a virtual device with no name, it just gives the program a FD for a device that we set (somehow) to be a virtual origin or snapshot. No device name ever appears on the filesystem. I have some misgivings about this idea because we then invite the situation where we can have multiple virtual devices on the same host, referring to the same snapshot. This ought to work for fine for our ddsnap and ddraid devices because they are designed as cluster devices, but I dunno. I'm still mulliing over the right thing to do there. This is just to let everybody know that the deficiencies of the current scheme are known, they are being thought about, and for now the result is some visible warts.

BUGS

Please report bugs at http://code.google.com/p/zumastor or mail them to zumastor@googlegroups.com.

VERSION

This man page is current for version 0.5 of ddsnap.

AUTHORS

Man page written by Jane Chiu. Original ddsnap snapshots coded by Daniel Phillips. Remote replication originally coded by Jane Chiu and Robert Nelson. Additional coding by Ross Combs.

CREDITS

ddsnap is distributed under the GNU public license, version 2. See the file COPYING for details.
This program uses zlib compression library and popt library. Many people sent patches, lent machines, gave advice and were generally helpful.

THANKS

Thanks to Google, Red Hat and Sistina Software for supporting this work. Special thanks to: Mike Todd, Joseph Dries and Matthew O'Keefe.
The home page of ddsnap is http://zumastor.org. This site may cover questions unanswered by this manual page. Mailing lists for support and development are available at zumastor@googlegroups.com

This document was created by man2html, using the manual pages.
Time: 18:45:01 GMT, January 29, 2008