README
¶
zrepl
zrepl is a one-stop ZFS backup & replication solution.
User Documentation
User Documentation can be found at zrepl.github.io.
Bug Reports
- If the issue is reproducible, enable debug logging, reproduce and capture the log.
- Open an issue on GitHub, with logs pasted as GitHub gists / inline.
Feature Requests
- Does you feature request require default values / some kind of configuration? If so, think of an expressive configuration example.
- Think of at least one use case that generalizes from your concrete application.
- Open an issue on GitHub with example conf & use case attached.
- Optional: Post a bounty on the issue, or contact Christian Schwarz for contract work.
The above does not apply if you already implemented everything. Check out the Coding Workflow section below for details.
Package Maintainer Information
- Follow the steps in
docs/installation.rst -> Compiling from Sourceand read the Makefile / shell scripts used in this process. - Make sure your distro is compatible with the paths in
docs/installation.rst. - Ship a default config that adheres to your distro's
hierand logging system. - Ship a service manager file and please try to upstream it to this repository.
dist/systemdcontains a Systemd unit template.
- Ship other material provided in
./dist, e.g. in/usr/share/zrepl/. - Use
make release ZREPL_VERSION='mydistro-1.2.3_1'- Your distro's name and any versioning supplemental to zrepl's (e.g. package revision) should be in this string
- Use
sudo make test-platformon a test system to validate that zrepl's abstractions on top of ZFS work with the system ZFS. - Make sure you are informed about new zrepl versions, e.g. by subscribing to GitHub's release RSS feed.
Developer Documentation
zrepl is written in Go and uses Go modules to manage dependencies. The documentation is written in ReStructured Text using the Sphinx framework.
Install build dependencies using ./lazy.sh devsetup.
lazy.sh uses python3-pip to fetch the build dependencies for the docs - you might want to use a venv.
If you just want to install the Go dependencies, run ./lazy.sh godep.
The test suite is split into pure Go tests (make test-go) and platform tests that interact with ZFS and thus generally require root privileges (sudo make test-platform).
Platform tests run on their own pool with the name zreplplatformtest, which is created using the file vdev in /tmp.
For a full code coverage profile, run make test-go COVER=1 && sudo make test-platform && make cover-merge.
An HTML report can be generated using make cover-html.
Code generation is triggered by make generate. Generated code is committed to the source tree.
Project Structure
├── artifacts # build artifcats generate by make
├── cli # wrapper around CLI package cobra
├── client # all subcommands that are not `daemon`
├── config # config data types (=> package yaml-config)
│ └── samples
├── daemon # the implementation of `zrepl daemon` subcommand
│ ├── filters
│ ├── hooks # snapshot hooks
│ ├── job # job implementations
│ ├── logging # logging outlets + formatters
│ ├── nethelpers
│ ├── prometheus
│ ├── pruner # pruner implementation
│ ├── snapper # snapshotter implementation
├── dist # supplemental material for users & package maintainers
├── docs # sphinx-based documentation
│ ├── **/*.rst # documentation in reStructuredText
│ ├── sphinxconf
│ │ └── conf.py # sphinx config (see commit 445a280 why its not in docs/)
│ ├── requirements.txt # pip3 requirements to build documentation
│ ├── publish.sh # shell script for automated rendering & deploy to zrepl.github.io repo
│ └── public_git # checkout of zrepl.github.io managed by above shell script
├── endpoint # implementation of replication endpoints (=> package replication)
├── logger # our own logger package
├── platformtest # test suite for our zfs abstractions (error classification, etc)
├── pruning # pruning rules (the logic, not the actual execution)
│ └── retentiongrid
├── replication
│ ├── driver # the driver of the replication logic (status reporting, error handling)
│ ├── logic # planning & executing replication steps via rpc
| | └── pdu # the generated gRPC & protobuf code used in replication (and endpoints)
│ └── report # the JSON-serializable report datastructures exposed to the client
├── rpc # the hybrid gRPC + ./dataconn RPC client: connects to a remote replication.Endpoint
│ ├── dataconn # Bulk data-transfer RPC protocol
│ ├── grpcclientidentity # adaptor to inject package transport's 'client identity' concept into gRPC contexts
│ ├── netadaptor # adaptor to convert a package transport's Connecter and Listener into net.* primitives
│ ├── transportmux # TCP connecter and listener used to split control & data traffic
│ └── versionhandshake # replication protocol version handshake perfomed on newly established connections
├── tlsconf # abstraction for Go TLS server + client config
├── transport # transport implementations
│ ├── fromconfig
│ ├── local
│ ├── ssh
│ ├── tcp
│ └── tls
├── util
├── version # abstraction for versions (filled during build by Makefile)
└── zfs # zfs(8) wrappers
Coding Workflow
- Open an issue when starting to hack on a new feature
- Commits should reference the issue they are related to
- Docs improvements not documenting new features do not require an issue.
Breaking Changes
Backward-incompatible changes must be documented in the git commit message and are listed in docs/changelog.rst.
- Config-breaking changes must contain a line
BREAK CONFIGin the commit message - Other breaking changes must contain a line
BREAKin the commit message
Glossary & Naming Inconsistencies
In ZFS, dataset refers to the objects filesystem, ZVOL and snapshot.
However, we need a word for filesystem & ZVOL but not a snapshot, bookmark, etc.
Toward the user, the following terminology is used:
- filesystem: a ZFS filesystem or a ZVOL
- filesystem version: a ZFS snapshot or a bookmark
Sadly, the zrepl implementation is inconsistent in its use of these words: variables and types are often named dataset when they in fact refer to a filesystem.
There will not be a big refactoring (an attempt was made, but it's destroying too much history without much gain).
However, new contributions & patches should fix naming without further notice in the commit message.
RPC debugging
Optionally, there are various RPC-related environment variables, that if set to something != "" will produce additional debug output on stderr:
https://github.com/zrepl/zrepl/blob/master/rpc/rpc_debug.go#L11
https://github.com/zrepl/zrepl/blob/master/rpc/dataconn/dataconn_debug.go#L11
https://github.com/zrepl/zrepl/blob/master/rpc/dataconn/stream/stream_debug.go#L11
https://github.com/zrepl/zrepl/blob/master/rpc/dataconn/heartbeatconn/heartbeatconn_debug.go#L11
Documentation
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
hooks
Package hooks implements pre- and post snapshot hooks.
|
Package hooks implements pre- and post snapshot hooks. |
|
logging/trace
package trace provides activity tracing via ctx through Tasks and Spans Basic Concepts Tracing can be used to identify where a piece of code spends its time.
|
package trace provides activity tracing via ctx through Tasks and Spans Basic Concepts Tracing can be used to identify where a piece of code spends its time. |
|
Package endpoint implements replication endpoints for use with package replication.
|
Package endpoint implements replication endpoints for use with package replication. |
|
Package replication implements replication of filesystems with existing versions (snapshots) from a sender to a receiver.
|
Package replication implements replication of filesystems with existing versions (snapshots) from a sender to a receiver. |
|
Package rpc implements zrepl daemon-to-daemon RPC protocol on top of a transport provided by package transport.
|
Package rpc implements zrepl daemon-to-daemon RPC protocol on top of a transport provided by package transport. |
|
dataconn/heartbeatconn/integration_test_variablereceiverate
This integration test exercises the behavior of heartbeatconn where the server is slow at handling the data received over the connection.
|
This integration test exercises the behavior of heartbeatconn where the server is slow at handling the data received over the connection. |
|
dataconn/microbenchmark
microbenchmark to manually test rpc/dataconn performance With stdin / stdout on client and server, simulating zfs send|recv piping ./microbenchmark -appmode server | pv -r > /dev/null ./microbenchmark -appmode client -direction recv < /dev/zero Without the overhead of pipes (just protocol performance, mostly useful with perf bc no bw measurement) ./microbenchmark -appmode client -direction recv -devnoopWriter -devnoopReader ./microbenchmark -appmode server -devnoopReader -devnoopWriter
|
microbenchmark to manually test rpc/dataconn performance With stdin / stdout on client and server, simulating zfs send|recv piping ./microbenchmark -appmode server | pv -r > /dev/null ./microbenchmark -appmode client -direction recv < /dev/zero Without the overhead of pipes (just protocol performance, mostly useful with perf bc no bw measurement) ./microbenchmark -appmode client -direction recv -devnoopWriter -devnoopReader ./microbenchmark -appmode server -devnoopReader -devnoopWriter |
|
dataconn/timeoutconn
package timeoutconn wraps a Wire to provide idle timeouts based on Set{Read,Write}Deadline.
|
package timeoutconn wraps a Wire to provide idle timeouts based on Set{Read,Write}Deadline. |
|
dataconn/timeoutconn/internal/wireevaluator
a tool to test whether a given transport implements the timeoutconn.Wire interface
|
a tool to test whether a given transport implements the timeoutconn.Wire interface |
|
grpcclientidentity
Package grpcclientidentity makes the client identity provided by github.com/zrepl/zrepl/daemon/transport/serve.{AuthenticatedListener,AuthConn} available to gRPC service handlers.
|
Package grpcclientidentity makes the client identity provided by github.com/zrepl/zrepl/daemon/transport/serve.{AuthenticatedListener,AuthConn} available to gRPC service handlers. |
|
grpcclientidentity/example
This package demonstrates how the grpcclientidentity package can be used to set up a gRPC greeter service.
|
This package demonstrates how the grpcclientidentity package can be used to set up a gRPC greeter service. |
|
grpcclientidentity/grpchelper
Package grpchelper wraps the adaptors implemented by package grpcclientidentity into a less flexible API which, however, ensures that the individual adaptor primitive's expectations are met and hence do not panic.
|
Package grpchelper wraps the adaptors implemented by package grpcclientidentity into a less flexible API which, however, ensures that the individual adaptor primitive's expectations are met and hence do not panic. |
|
netadaptor
Package netadaptor implements an adaptor from transport.AuthenticatedListener to net.Listener.
|
Package netadaptor implements an adaptor from transport.AuthenticatedListener to net.Listener. |
|
transportmux
Package transportmux wraps a transport.{Connecter,AuthenticatedListener} to distinguish different connection types based on a label sent from client to server on connection establishment.
|
Package transportmux wraps a transport.{Connecter,AuthenticatedListener} to distinguish different connection types based on a label sent from client to server on connection establishment. |
|
versionhandshake
Package versionhandshake wraps a transport.{Connecter,AuthenticatedListener} to add an exchange of protocol version information on connection establishment.
|
Package versionhandshake wraps a transport.{Connecter,AuthenticatedListener} to add an exchange of protocol version information on connection establishment. |
|
Package transport defines a common interface for network connections that have an associated client identity.
|
Package transport defines a common interface for network connections that have an associated client identity. |
|
fromconfig
Package fromconfig instantiates transports based on zrepl config structures (see package config).
|
Package fromconfig instantiates transports based on zrepl config structures (see package config). |
|
util
|
|
|
chainlock
package chainlock implements a mutex whose Lock and Unlock methods return the lock itself, to enable chaining.
|
package chainlock implements a mutex whose Lock and Unlock methods return the lock itself, to enable chaining. |
|
devnoop
package devnoop provides an io.ReadWriteCloser that never errors and always reports reads / writes to / from buffers as complete.
|
package devnoop provides an io.ReadWriteCloser that never errors and always reports reads / writes to / from buffers as complete. |
|
zfscmd
Package zfscmd provides a wrapper around packate os/exec.
|
Package zfscmd provides a wrapper around packate os/exec. |
Click to show internal directories.
Click to hide internal directories.