From owner-svn-doc-projects@FreeBSD.ORG Fri Jan 31 19:37:24 2014 Return-Path: Delivered-To: svn-doc-projects@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [8.8.178.115]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id E5BC69F4; Fri, 31 Jan 2014 19:37:24 +0000 (UTC) Received: from dmz-mailsec-scanner-5.mit.edu (dmz-mailsec-scanner-5.mit.edu [18.7.68.34]) by mx1.freebsd.org (Postfix) with ESMTP id 4E21A11F4; Fri, 31 Jan 2014 19:37:22 +0000 (UTC) X-AuditID: 12074422-f79526d000000c47-a8-52ebfa3f6aaf Received: from mailhub-auth-2.mit.edu ( [18.7.62.36]) (using TLS with cipher AES256-SHA (256/256 bits)) (Client did not present a certificate) by dmz-mailsec-scanner-5.mit.edu (Symantec Messaging Gateway) with SMTP id D7.64.03143.F3AFBE25; Fri, 31 Jan 2014 14:32:15 -0500 (EST) Received: from outgoing.mit.edu (outgoing-auth-1.mit.edu [18.9.28.11]) by mailhub-auth-2.mit.edu (8.13.8/8.9.2) with ESMTP id s0VJWEaE013398; Fri, 31 Jan 2014 14:32:14 -0500 Received: from multics.mit.edu (system-low-sipb.mit.edu [18.187.2.37]) (authenticated bits=56) (User authenticated as kaduk@ATHENA.MIT.EDU) by outgoing.mit.edu (8.13.8/8.12.4) with ESMTP id s0VJWCCl010302 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NOT); Fri, 31 Jan 2014 14:32:13 -0500 Received: (from kaduk@localhost) by multics.mit.edu (8.12.9.20060308) id s0VJWBs4028062; Fri, 31 Jan 2014 14:32:12 -0500 (EST) Date: Fri, 31 Jan 2014 14:32:11 -0500 (EST) From: Benjamin Kaduk To: Benedict Reuschling Subject: Re: svn commit: r43697 - projects/zfsupdate-201307/en_US.ISO8859-1/books/handbook/zfs In-Reply-To: <201401301900.s0UJ09Ua083494@svn.freebsd.org> Message-ID: References: <201401301900.s0UJ09Ua083494@svn.freebsd.org> User-Agent: Alpine 1.10 (GSO 962 2008-03-14) MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII; format=flowed X-Brightmail-Tracker: H4sIAAAAAAAAA+NgFnrNIsWRmVeSWpSXmKPExsUixG6nomv/63WQwbzFnBbnj6hb/Ph4iMli 4ZnVzA7MHjM+zWcJYIzisklJzcksSy3St0vgypjX+oW1YHF2xY+e+8wNjAtDuhg5OSQETCT+ ndrNCmGLSVy4t56ti5GLQ0hgNpPE1bUL2UASQgIbGSXWX0+DSBxikthw6h8zhNPAKDH/xCcW kCoWAW2Jpu67zCA2m4CKxMw3G8G6RQQ0JWa3rWYCsZkFbCQmPFjADmILCyRIbFz+DizOKWAl cfHHUUYQm1fAUWLpsa1AJ3EALbCUeD1bECQsKqAjsXr/FBaIEkGJkzOfsECMtJQ49+c62wRG wVlIUrOQpBYwMq1ilE3JrdLNTczMKU5N1i1OTszLSy3SNdXLzSzRS00p3cQIDlMXpR2MPw8q HWIU4GBU4uFtOPE6SIg1say4MvcQoyQHk5Io7/mPQCG+pPyUyozE4oz4otKc1OJDjBIczEoi vFxlQDnelMTKqtSifJiUNAeLkjjvLQ77ICGB9MSS1OzU1ILUIpisDAeHkgRv4U+gRsGi1PTU irTMnBKENBMHJ8hwHqDhjCA1vMUFibnFmekQ+VOMilLivFEgCQGQREZpHlwvLI28YhQHekWY NxGkigeYguC6XwENZgIa3HMAbHBJIkJKqoExwbpfPSyqXcL0/S6j0HXJvqUa5q+mHY1gF93d Enfkzdcoi/+Lmm+v/J14svTpfV/N7znrHROVVl9oudH959nrXhGnJ3nTr2dyKEntDnhhY+uy u0DFtL7gh7XR8/DyVS7zStZla/xecF0tJ/jwgbMVUzf922x37HPUjyMXLWdI3zzyQ+ep4t7H SizFGYmGWsxFxYkA5f0/L/4CAAA= Cc: svn-doc-projects@freebsd.org, doc-committers@freebsd.org X-BeenThere: svn-doc-projects@freebsd.org X-Mailman-Version: 2.1.17 Precedence: list List-Id: SVN commit messages for doc projects trees List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 31 Jan 2014 19:37:25 -0000 On Thu, 30 Jan 2014, Benedict Reuschling wrote: > Log: > Add a section about basic zfs send and receive. This is based on an older > example and might need updates to represent the current zfs version we have. > It shows how to send zfs data streams locally and remote (via SSH) with > example commands and output. > > Modified: > projects/zfsupdate-201307/en_US.ISO8859-1/books/handbook/zfs/chapter.xml > > Modified: projects/zfsupdate-201307/en_US.ISO8859-1/books/handbook/zfs/chapter.xml > ============================================================================== > --- projects/zfsupdate-201307/en_US.ISO8859-1/books/handbook/zfs/chapter.xml Thu Jan 30 18:17:31 2014 (r43696) > +++ projects/zfsupdate-201307/en_US.ISO8859-1/books/handbook/zfs/chapter.xml Thu Jan 30 19:00:09 2014 (r43697) > @@ -1250,7 +1250,243 @@ tank custom:costcenter - > > ZFS Replication > > - > + Keeping the data on a single pool in one location exposes > + it to risks like theft, natural and human desasters. Keeping "disasters". > + regular backups of the entire pool is vital when data needs to > + be restored. ZFS provides a built-in serialization feature > + that can send a stream representation of the data to standard > + output. Using this technique, it is possible to not only > + store the data on another pool connected to the local system, > + but also to send it over a network to another system that runs > + ZFS. To achieve this replication, ZFS uses the filesystem s/the// > + snapshots (see the section on + linkend="zfs-zfs-snapshot">ZFS snapshots on how they s/on/for/ > + work) to send them from one location to another. The commands > + for this operation are zfs send and > + zfs receive, respectively. > + > + The following examples will demonstrate the functionality > + of ZFS replication using these two pools: > + > + &prompt.root; zpool list > +NAME SIZE ALLOC FREE CAP DEDUP HEALTH ALTROOT > +backup 960M 77K 896M 0% 1.00x ONLINE - > +mypool 984M 43.7M 940M 4% 1.00x ONLINE - > + > + The pool named mypool is the > + primary pool where data is written to and read from on a > + regular basis. A second pool, > + backup is used as a standby in case > + the primary pool becomes offline. Note that this is not done > + automatically by ZFS, but rather done by a system > + administrator in case it is needed. First, a snapshot is > + created on mypool to have a backup I don't really think that "backup" is the best characterization of what is going on, here. It's really just a snapshot, but we used that word already. Maybe 'copy'? > + of the current state of the data to send to the pool > + backup. > + > + &prompt.root; zfs snapshot mypool@backup1 > +&prompt.root; zfs list -t snapshot > +NAME USED AVAIL REFER MOUNTPOINT > +mypool@backup1 0 - 43.6M - > + > + Now that a snapshot exists, zfs send > + can be used to create a stream representing the contents of > + the snapshot locally or remote to another pool. The stream "remotely", I think? > + must be written to the standard output, otherwise ZFS will > + produce an error like in this example: > + > + &prompt.root; zfs send mypool@backup1 > +Error: Stream can not be written to a terminal. > +You must redirect standard output. > + > + The correct way to use zfs send is to > + redirect it to a location like the mounted backup pool. > + Afterwards, that pool should have the size of the snapshot > + allocated, which means all the data contained in the snapshot > + was stored on the backup pool. > + > + &prompt.root; zfs send mypool@backup1 > /backup/backup1 > +&prompt.root; zpool list > +NAME SIZE ALLOC FREE CAP DEDUP HEALTH ALTROOT > +backup 960M 63.7M 896M 6% 1.00x ONLINE - > +mypool 984M 43.7M 940M 4% 1.00x ONLINE - > + > + The zfs send transferred all the data > + in the snapshot called backup1 to > + the pool named backup. Creating > + and sending these snapshots could be done automatically by a > + cron job. > + > + > + ZFS Incremental Backups > + > + Another feature of zfs send is that > + it can determine the difference between two snapshots to > + only send what has changed between the two. This results in > + saving disk space and time for the transfer to another pool. > + The following example demonstrates this: Would just "For example:" suffice here? It is more concise. > + > + &prompt.root; zfs snapshot mypool@backup2 > +&prompt.root; zfs list -t snapshot > +NAME USED AVAIL REFER MOUNTPOINT > +mypool@backup1 5.72M - 43.6M - > +mypool@backup2 0 - 44.1M - > +&prompt.root; zpool list > +NAME SIZE ALLOC FREE CAP DEDUP HEALTH ALTROOT > +backup 960M 61.7M 898M 6% 1.00x ONLINE - > +mypool 960M 50.2M 910M 5% 1.00x ONLINE - > + > + A second snapshot called > + backup2 was created. This second > + snapshot contains only the changes on the ZFS filesystem > + between now and the last snapshot, > + backup1. Using the > + -i flag to zfs send > + and providing both snapshots, an incremental snapshot can be > + transferred, containing only the data that has > + changed. > + > + &prompt.root; zfs send -i mypool@backup1 mypool@backup2 > /backup/incremental > +&prompt.root; zpool list > +NAME SIZE ALLOC FREE CAP DEDUP HEALTH ALTROOT > +backup 960M 80.8M 879M 8% 1.00x ONLINE - > +mypool 960M 50.2M 910M 5% 1.00x ONLINE - > +&prompt.root; ls -lh /backup > +total 82247 > +drwxr-xr-x 1 root wheel 61M Dec 3 11:36 backup1 > +drwxr-xr-x 1 root wheel 18M Dec 3 11:36 incremental > + > + The incremental stream was successfully transferred and > + the file on disk is smaller than any of the two snapshots > + backup1 or > + backup2. This shows that it only > + contains the differences, which is much faster to transfer > + and saves disk space by not copying the complete pool each > + time. This is useful when having to rely on slow networks > + or when costs per transferred byte have to be > + considered. > + > + > + > + Receiving ZFS Data Streams > + > + Up until now, only the data streams in binary form were > + sent to other pools. To get to the actual data contained in > + those streams, the reverse operation of zfs > + send has to be used to transform the streams > + back into files and directories. The command is called > + zfs receive and has also a short version: > + zfs recv. The example below combines > + zfs send and zfs > + receive using a pipe to copy the data from one > + pool to another. This way, the data can be used directly on > + the receiving pool after the transfer is complete. > + > + &prompt.root; zfs send mypool@backup1 | zfs receive backup/backup1 > +&prompt.root; ls -lh /backup > +total 431 > +drwxr-xr-x 4219 root wheel 4.1k Dec 3 11:34 backup1 > + > + The directory backup1 does > + contain all the data, which were part of the snapshot of the > + same name. Since this originally was a complete filesystem > + snapshot, the listing of all ZFS filesystems for this pool > + is also updated and shows the > + backup1 entry. > + > + &prompt.root; zfs list > +NAME USED AVAIL REFER MOUNTPOINT > +backup 43.7M 884M 32K /backup > +backup/backup1 43.5M 884M 43.5M /backup/backup1 > +mypool 50.0M 878M 44.1M /mypool > + > + A new filesystem, backup1 is > + available and has the same size as the snapshot it was > + created from. It is up to the user to decide whether the > + streams should be transformed back into filesystems directly > + to have a cold-standby for emergencies or to just keep the > + streams and transform them later when required. Sending and > + receiving can be automated so that regular backups are > + created on a second pool for backup purposes. > + > + > + > + Sending Encrypted Backups over SSH > + > + Although sending streams to another system over the > + network is a good way to keep a remote backup, it does come > + with a drawback. All the data sent over the network link is > + not encrypted, allowing anyone to intercept and transform > + the streams back into data without the knowledge of the > + sending user. This is an unacceptable situation, especially > + when sending the streams over the internet to a remote host > + with multiple hops in between where such malicious data > + collection can occur. Fortunately, there is a solution > + available to the problem that does not require the > + encryption of the data on the pool itself. To make sure the > + network connection between both systems is securely > + encrypted, SSH can be used. > + Since ZFS only requires the stream to be redirected from > + standard output, it is relatively easy to pipe it through > + SSH. This paragraph seems rather wordy, though I don't think I have any concrete suggestions at the moment. > + > + A few settings and security precautions have to be made > + before this can be done. Since this chapter is about ZFS > + and not about configuring SSH, it only lists the things > + required to perform the encrypted zfs > + send operation. The following settings should > + be made: > + > + > + > + Passwordless SSH access between sending and > + receiving host using SSH keys > + > + > + > + The root user needs to be able to > + log into the receiving system because only that user can > + send streams from the pool. SSH should be configured so > + that root can only execute > + zfs recv and nothing else to prevent > + users that might have hijacked this account from doing > + any harm on the system. This paragraph is a little confusing about what happens on the sending and receiving systems. (For example, at first I was confused by the first sentence, thinking that it was saying that the receiving system would be sending streams from the pool.) Do both the send and receive have to happen as root on the respective machines? I also think that the restriction to 'zfs recv' should apply only to the particular ssh key which is doing the automated backups; it would be absurd to prevent root login from one server to another just because there is a backup relationship in place. > + > + > + > + After these security measures have been put into place > + and root can connect passwordless via SSH I think that "via passwordless SSH" is the more conventional phrasing. Also, do we want markup around SSH? -Ben > + to the receiving system, the encrypted stream can be sent > + using the following commands: > + > + &prompt.root; zfs snapshot -r mypool/home@monday > +&prompt.root; zfs send -R mypool/home@monday | ssh backuphost zfs recv -dvu backuppool