-
Notifications
You must be signed in to change notification settings - Fork 0
/
quickstart.html
240 lines (218 loc) · 16.2 KB
/
quickstart.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
<!DOCTYPE html>
<html class="writer-html5" lang="en" >
<head>
<meta charset="utf-8" /><meta name="generator" content="Docutils 0.18.1: http://docutils.sourceforge.net/" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Quick Start by Use Case — zrepl documentation</title>
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
<link rel="stylesheet" href="_static/banner.css" type="text/css" />
<!--[if lt IE 9]>
<script src="_static/js/html5shiv.min.js"></script>
<![endif]-->
<script src="_static/jquery.js?v=5d32c60e"></script>
<script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
<script src="_static/documentation_options.js?v=5929fcd5"></script>
<script src="_static/doctools.js?v=888ff710"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="_static/js/theme.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Continuous Backup of a Server" href="quickstart/continuous_server_backup.html" />
<link rel="prev" title="zrepl - ZFS replication" href="index.html" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" >
<a href="index.html" class="icon icon-home">
zrepl
<img src="_static/zrepl.svg" class="logo" alt="Logo"/>
</a>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
<ul class="current">
<li class="toctree-l1 current"><a class="current reference internal" href="#">Quick Start by Use Case</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#install-zrepl">Install zrepl</a></li>
<li class="toctree-l2"><a class="reference internal" href="#overview-of-how-zrepl-works">Overview Of How zrepl Works</a></li>
<li class="toctree-l2"><a class="reference internal" href="#configuration-examples">Configuration Examples</a><ul>
<li class="toctree-l3"><a class="reference internal" href="quickstart/continuous_server_backup.html">Continuous Backup of a Server</a></li>
<li class="toctree-l3"><a class="reference internal" href="quickstart/backup_to_external_disk.html">Local Snapshots + Offline Backup to an External Disk</a></li>
<li class="toctree-l3"><a class="reference internal" href="quickstart/fan_out_replication.html">Fan-out replication</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#apply-configuration-changes">Apply Configuration Changes</a></li>
<li class="toctree-l2"><a class="reference internal" href="#watch-it-work">Watch it Work</a></li>
<li class="toctree-l2"><a class="reference internal" href="#what-next">What Next?</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="installation.html">Installation</a></li>
<li class="toctree-l1"><a class="reference internal" href="configuration.html">Configuration</a></li>
<li class="toctree-l1"><a class="reference internal" href="usage.html">Usage</a></li>
<li class="toctree-l1"><a class="reference internal" href="pr.html">Talks & Presentations</a></li>
<li class="toctree-l1"><a class="reference internal" href="changelog.html">Changelog</a></li>
<li class="toctree-l1"><a class="reference external" href="https://github.com/zrepl/zrepl">GitHub Repository & Issue Tracker</a></li>
<li class="toctree-l1"><a class="reference external" href="https://matrix.to/#/#zrepl:matrix.org">Chat: Matrix</a></li>
<li class="toctree-l1"><a class="reference internal" href="supporters.html">Supporters</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="index.html">zrepl</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="Page navigation">
<ul class="wy-breadcrumbs">
<li><a href="index.html" class="icon icon-home" aria-label="Home"></a></li>
<li class="breadcrumb-item active">Quick Start by Use Case</li>
<li class="wy-breadcrumbs-aside">
<a href="https://github.com/zrepl/zrepl/blob/master/docs/quickstart.rst" class="fa fa-github"> Edit on GitHub</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<section id="quick-start-by-use-case">
<span id="quickstart-toc"></span><h1>Quick Start by Use Case<a class="headerlink" href="#quick-start-by-use-case" title="Link to this heading"></a></h1>
<p>The goal of this quick-start guide is to give you an impression of how zrepl can accomodate your use case.</p>
<section id="install-zrepl">
<h2>Install zrepl<a class="headerlink" href="#install-zrepl" title="Link to this heading"></a></h2>
<p>Follow the <a class="reference internal" href="installation.html#installation-toc"><span class="std std-ref">OS-specific installation instructions</span></a> and come back here.</p>
</section>
<section id="overview-of-how-zrepl-works">
<h2>Overview Of How zrepl Works<a class="headerlink" href="#overview-of-how-zrepl-works" title="Link to this heading"></a></h2>
<p>Check out the <a class="reference internal" href="configuration/overview.html#job-overview"><span class="std std-ref">overview section</span></a> to get a rough idea of what you are going to configure in the next step, then come back here.</p>
</section>
<section id="configuration-examples">
<h2>Configuration Examples<a class="headerlink" href="#configuration-examples" title="Link to this heading"></a></h2>
<p>zrepl is configured through a YAML configuration file in <code class="docutils literal notranslate"><span class="pre">/etc/zrepl/zrepl.yml</span></code>.
We have prepared example use cases that show-case typical deployments and different functionality of zrepl.
We encourage you to read through all of the examples to get an idea of what zrepl has to offer, and how you can mix-and-match configurations for your use case.
Keep the <a class="reference internal" href="configuration.html#configuration-toc"><span class="std std-ref">full config documentation</span></a> handy if a config snippet is unclear.</p>
<p><strong>Example Use Cases</strong></p>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="quickstart/continuous_server_backup.html">Continuous Backup of a Server</a></li>
<li class="toctree-l1"><a class="reference internal" href="quickstart/backup_to_external_disk.html">Local Snapshots + Offline Backup to an External Disk</a></li>
<li class="toctree-l1"><a class="reference internal" href="quickstart/fan_out_replication.html">Fan-out replication</a></li>
</ul>
</div>
<p>Use <code class="docutils literal notranslate"><span class="pre">zrepl</span> <span class="pre">configcheck</span></code> to validate your configuration.
No output indicates that everything is fine.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Please open an issue on GitHub if your use case for zrepl is significantly different from those listed above.
Or even better, write it up in the same style as above and open a PR!</p>
</div>
</section>
<section id="apply-configuration-changes">
<span id="quickstart-apply-config"></span><h2>Apply Configuration Changes<a class="headerlink" href="#apply-configuration-changes" title="Link to this heading"></a></h2>
<p>We hope that you have found a configuration that fits your use case.
Use <code class="docutils literal notranslate"><span class="pre">zrepl</span> <span class="pre">configcheck</span></code> once again to make sure the config is correct (output indicates that everything is fine).
Then restart the zrepl daemon on all systems involved in the replication, likely using <code class="docutils literal notranslate"><span class="pre">service</span> <span class="pre">zrepl</span> <span class="pre">restart</span></code> or <code class="docutils literal notranslate"><span class="pre">systemctl</span> <span class="pre">restart</span> <span class="pre">zrepl</span></code>.</p>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>Please <a class="reference internal" href="configuration/prune.html#prune"><span class="std std-ref">read up carefully</span></a> on the pruning rules before applying the config.
In particular, note that most example configs apply to all snapshots, not just zrepl-created snapshots.
Use the following keep rule on sender and receiver to prevent this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">-</span> <span class="nb">type</span><span class="p">:</span> <span class="n">regex</span>
<span class="n">negate</span><span class="p">:</span> <span class="n">true</span>
<span class="n">regex</span><span class="p">:</span> <span class="s2">"^zrepl_.*"</span> <span class="c1"># <- the 'prefix' specified in snapshotting.prefix</span>
</pre></div>
</div>
</div>
</section>
<section id="watch-it-work">
<h2>Watch it Work<a class="headerlink" href="#watch-it-work" title="Link to this heading"></a></h2>
<p>Run <code class="docutils literal notranslate"><span class="pre">zrepl</span> <span class="pre">status</span></code> on the active side of the replication setup to monitor snaphotting, replication and pruning activity.
To re-trigger replication (snapshots are separate!), use <code class="docutils literal notranslate"><span class="pre">zrepl</span> <span class="pre">signal</span> <span class="pre">wakeup</span> <span class="pre">JOBNAME</span></code>.
(refer to the example use case document if you are uncertain which job you want to wake up).</p>
<p>You can also use basic UNIX tools to inspect see what’s going on.
If you like tmux, here is a handy script that works on FreeBSD:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pkg</span> <span class="n">install</span> <span class="n">gnu</span><span class="o">-</span><span class="n">watch</span> <span class="n">tmux</span>
<span class="n">tmux</span> <span class="n">new</span> <span class="o">-</span><span class="n">s</span> <span class="n">zrepl</span> <span class="o">-</span><span class="n">d</span>
<span class="n">tmux</span> <span class="n">split</span><span class="o">-</span><span class="n">window</span> <span class="o">-</span><span class="n">t</span> <span class="n">zrepl</span> <span class="s2">"tail -f /var/log/messages"</span>
<span class="n">tmux</span> <span class="n">split</span><span class="o">-</span><span class="n">window</span> <span class="o">-</span><span class="n">t</span> <span class="n">zrepl</span> <span class="s2">"gnu-watch 'zfs list -t snapshot -o name,creation -s creation'"</span>
<span class="n">tmux</span> <span class="n">split</span><span class="o">-</span><span class="n">window</span> <span class="o">-</span><span class="n">t</span> <span class="n">zrepl</span> <span class="s2">"zrepl status"</span>
<span class="n">tmux</span> <span class="n">select</span><span class="o">-</span><span class="n">layout</span> <span class="o">-</span><span class="n">t</span> <span class="n">zrepl</span> <span class="n">tiled</span>
<span class="n">tmux</span> <span class="n">attach</span> <span class="o">-</span><span class="n">t</span> <span class="n">zrepl</span>
</pre></div>
</div>
<p>The Linux equivalent might look like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># make sure tmux is installed & let's assume you use systemd + journald</span>
<span class="n">tmux</span> <span class="n">new</span> <span class="o">-</span><span class="n">s</span> <span class="n">zrepl</span> <span class="o">-</span><span class="n">d</span>
<span class="n">tmux</span> <span class="n">split</span><span class="o">-</span><span class="n">window</span> <span class="o">-</span><span class="n">t</span> <span class="n">zrepl</span> <span class="s2">"journalctl -f -u zrepl.service"</span>
<span class="n">tmux</span> <span class="n">split</span><span class="o">-</span><span class="n">window</span> <span class="o">-</span><span class="n">t</span> <span class="n">zrepl</span> <span class="s2">"watch 'zfs list -t snapshot -o name,creation -s creation'"</span>
<span class="n">tmux</span> <span class="n">split</span><span class="o">-</span><span class="n">window</span> <span class="o">-</span><span class="n">t</span> <span class="n">zrepl</span> <span class="s2">"zrepl status"</span>
<span class="n">tmux</span> <span class="n">select</span><span class="o">-</span><span class="n">layout</span> <span class="o">-</span><span class="n">t</span> <span class="n">zrepl</span> <span class="n">tiled</span>
<span class="n">tmux</span> <span class="n">attach</span> <span class="o">-</span><span class="n">t</span> <span class="n">zrepl</span>
</pre></div>
</div>
</section>
<section id="what-next">
<h2>What Next?<a class="headerlink" href="#what-next" title="Link to this heading"></a></h2>
<ul class="simple">
<li><p>Read more about <a class="reference internal" href="configuration.html#configuration-toc"><span class="std std-ref">configuration format, options & job types</span></a></p></li>
<li><p>Configure <a class="reference internal" href="configuration/logging.html#logging"><span class="std std-ref">logging</span></a> & <a class="reference internal" href="configuration/monitoring.html#monitoring"><span class="std std-ref">monitoring</span></a>.</p></li>
</ul>
</section>
</section>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="index.html" class="btn btn-neutral float-left" title="zrepl - ZFS replication" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
<a href="quickstart/continuous_server_backup.html" class="btn btn-neutral float-right" title="Continuous Backup of a Server" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
</div>
<hr/>
<div role="contentinfo">
<p>© Copyright 2017-2023, Christian Schwarz.</p>
</div>
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
<a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<div class="rst-versions" data-toggle="rst-versions" role="note" aria-label="versions">
<span class="rst-current-version" data-toggle="rst-current-version">
<span class="fa fa-book"> Other Versions</span>
v: stable
<span class="fa fa-caret-down"></span>
</span>
<div class="rst-other-versions">
<dl>
<dt>Tags</dt>
<dd><a href="v0.6.1/quickstart.html">v0.6.1</a></dd>
<dd><a href="v0.5.0/quickstart.html">v0.5.0</a></dd>
<dd><a href="v0.4.0/quickstart.html">v0.4.0</a></dd>
<dd><a href="v0.3.1/quickstart.html">v0.3.1</a></dd>
<dd><a href="v0.2.1/index.html">v0.2.1</a></dd>
<dd><a href="v0.1.1/index.html">v0.1.1</a></dd>
</dl>
<dl>
<dt>Branches</dt>
<dd><a href="quickstart.html">stable</a></dd>
<dd><a href="master/quickstart.html">master</a></dd>
</dl>
</div>
</div><script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>