From ddb123ca8e67c65d778791516f01fb93ed06d28d Mon Sep 17 00:00:00 2001 From: Reese Sapphire Date: Fri, 23 Sep 2022 21:58:36 -0500 Subject: [PATCH] turn suggestions.md into a man page with pandoc * fixed some typos, phrasing, and formatting issues + added single-line script to convert markdown to man page format (so you don't have to remember how to do it each time) + also left a compiled manpage in the root. the `.7` extension is the number for the section titled "miscellaneous (including macro packages and conventions)". to use it you just copy the output file to /usr/share/man/man7/ and then do `man suggestions` (works on my machine) --- manpage.sh | 3 + suggestions.7 | 230 +++++++++++++++++++++++++++++++++++++++++++++++++ suggestions.md | 60 ++++++------- 3 files changed, 264 insertions(+), 29 deletions(-) create mode 100755 manpage.sh create mode 100644 suggestions.7 diff --git a/manpage.sh b/manpage.sh new file mode 100755 index 0000000..eaf9fd6 --- /dev/null +++ b/manpage.sh @@ -0,0 +1,3 @@ +#!/bin/sh + +pandoc --standalone --to man suggestions.md -o suggestions.7 diff --git a/suggestions.7 b/suggestions.7 new file mode 100644 index 0000000..9413381 --- /dev/null +++ b/suggestions.7 @@ -0,0 +1,230 @@ +.\" Automatically generated by Pandoc 2.19 +.\" +.\" Define V font for inline verbatim, using C font in formats +.\" that render this, and otherwise B font. +.ie "\f[CB]x\f[]"x" \{\ +. ftr V B +. ftr VI BI +. ftr VB B +. ftr VBI BI +.\} +.el \{\ +. ftr V CR +. ftr VI CI +. ftr VB CB +. ftr VBI CBI +.\} +.TH "Suggestions for setting up your backup account" "" "" "" "" +.hy +.SH Introduction +.PP +Hello! +Welcome to your LayerZero members-only bonus premium backup server! +I (zico) set this up to have a remote backup for myself and to offer +this to the wonderful people of Cyberia Computer Club. +.PP +As you probably know by being able to read this file, the server is set +up where each user gets a shell account with ssh access. +Each account has the same quota size which is probably enough to store +your documents, software projects, and important photos, but not enough +for your legally-acquired linux iso collection (unless someone wants to +donate some large disks). +.PP +The server is encrypted at rest (when the power is off, essentially), +including all the home directories. +You are also encouraged to encrypt your files yourself with tools like +restic, borg, rsync, or the included zfs. +.SH How to use your account +.PP +This server is intended to be for personal backups. +A place where you can store your precious cat pics, secret documents, +and traditional family hotdish recipes. +Although this is a shell account, please don\[cq]t use this to run +services from unless they relate directly to backing up your stuff. +I\[cq]d like this to remain a single-purpose server as it is not a +powerful box. +.PP +Since you have ssh access to your account, any software that can backup +over ssh is available to you! +Most backup software these days can use ssh as a backend, and almost all +of the tried and true cli methods can too. +.PP +The accounts themselves are reasonably locked-down, and by design allow +you to throw bits into the filesystem and not much else. +I\[cq]m very open to suggestions on how to make this a better experience +for people, so please ping me if this model isn\[cq]t working for what +you want to do. +.SH Backup Software +.PP +There is no one best backup software, and this server doesn\[cq]t prefer +one in particular. +As long as it can use ssh, it will work with your shell account. +Here are some suggestions, organized into cli and gui. +.SS CLI Backup Softare +.IP \[bu] 2 +rsync +.RS 2 +.IP \[bu] 2 +tried and true +.IP \[bu] 2 +flexible and has a million examples on the internet +.IP \[bu] 2 +lacking some nice features like built-in encryption +.RE +.IP \[bu] 2 +rsnapshot +.RS 2 +.IP \[bu] 2 +based on rsync, but more oriented towards backups +.IP \[bu] 2 +uses a config file +.IP \[bu] 2 +no built-in encryption +.RE +.IP \[bu] 2 +restic +.RS 2 +.IP \[bu] 2 +\[lq]modern\[rq] cli backup with modern features (encryption, +deduplication) +.IP \[bu] 2 +very flexible, can backup to a wide variety of sources +.IP \[bu] 2 +can be more complex to understand +.RE +.IP \[bu] 2 +borg +.RS 2 +.IP \[bu] 2 +similar to restic, a bit older +.IP \[bu] 2 +has a gui companion app called Vorta +.IP \[bu] 2 +needs a helper script to run automatically +.RE +.IP \[bu] 2 +zfs +.RS 2 +.IP \[bu] 2 +see zfs section +.RE +.IP \[bu] 2 +sanoid/syncoid +.RS 2 +.IP \[bu] 2 +see zfs section +.RE +.SS GUI backup software +.IP \[bu] 2 +Duplicati +.RS 2 +.IP \[bu] 2 +WebUI +.IP \[bu] 2 +can be very simple or very complex, depending on your usecase +.IP \[bu] 2 +huge number of options and flexibility, many possible backup endpoints +.RE +.IP \[bu] 2 +Bacula +.IP \[bu] 2 +Back in Time +.IP \[bu] 2 +Deja Dup +.IP \[bu] 2 +Timeshift +.PP +There are many many backup software solutions. +If you need help finding one that works for you, please reach out to me +and I\[cq]d be happy to help you. +.SH ZFS +.PP +ZFS is a weird and wonderful kind of filesystem that incorporates both +the actual low-level regular file system stuff and the tools to manage +it into one piece of software. +If you haven\[cq]t used it before, it will probably be a bit strange at +first. +.PP +For an introduction to ZFS terms and concepts, this article by Jim +Salter is an excellent resource: +.PD 0 +.P +.PD +https://web.archive.org/web/20220902082642/https://arstechnica.com/information-technology/2020/05/zfs-101-understanding-zfs-storage-and-performance/ +.PP +Your access to ZFS on this system is somewhat limited to interacting +with your home directory. +You have the necessary permissions to create and destroy new datasets, +snapshot them, receive a snapshot remotely or send it somewhere else on +the internet, and much more. +To check all the permissions you have on your home folder, run +\f[V]zfs allow backup-pool/home/$(whoami)\f[R] (use +\f[V]man zfs-allow\f[R] to find out what they mean). +.PP +There are technically two versions of zfs, the \[lq]original\[rq] Oracle +zfs that they acquired with the takeover of Sun Microsystems, and the +OpenZFS version developed collaboratively by many people across many +companies. +Almost every deployment in the wild is the OpenZFS version, and there +are small but substantial differences between the two. +That being said, most of the Oracle zfs docs come up first when you +search for info, and they can generally be used for OpenZFS as well. +This server uses the OpenZFS version. +.SS zfs send/receive +.PP +This is the native zfs way to move copies of filesystems around. +If you\[cq]ve worked with databases before, it\[cq]s somewhat similar to +a dump and restore operation. +The basic concept is that you (or an automated tool) take a snapshot of +a filesystem, and then copy that snapshot to another zfs filesystem (or +computer), which is set up to receive that stream. +.PP +This setup requires that zfs is the filesystem at both the sending and +receiving location, so it won\[cq]t work for most default linux +installations. +It also doesn\[cq]t have a gui that I know of, so it isn\[cq]t as +friendly as other solutions. +It is, however, definitely the technically fastest incremental backup +you could possibly find. +Due to zfs checksumming each block of data, seeing what changed between +snapshots is extremely fast as zfs only needs to check the checksums, +not the actualy file contents. +Other backup solutions have similar solutions, but are not as fast as +they are not low-level filesystems. +.PP +Using zfs send/receive for simple cases is pretty simple. +For example: +.IP +.nf +\f[C] +$ zfs snapshot zroot/home/zico\[at]snapshot1 +$ zfs send zroot/home/zico\[at]snapshot1 | ssh zico\[at]backupserver zfs receive backup-pool/home +\f[R] +.fi +.PP +The Oracle ZFS docs on send/receive are pretty good and are useful for +the OpenZFS version as well: +.PD 0 +.P +.PD +https://docs.oracle.com/cd/E18752_01/html/819-5461/gbchx.html +.SS sanoid/syncoid +.PP +\[lq]Sanoid is a policy-driven snapshot management tool for ZFS +filesystems\[rq], according to the github readme. +It\[cq]s one of many zfs send management tools, and it\[cq]s the one +I\[cq]m most familiar with. +Sanoid allows you to set a config file for how many snapshots you want +zfs to take for each filesystem, and how long to keep them. +The companion tool Syncoid will send snapshots of your configured +filesystems to another zfs pool, whether that\[cq]s on the same computer +or a remote server like this one. +It\[cq]s a very handy tool to automate zfs backups. +.PP +Sanoid and syncoid can be found at their github page: +.PD 0 +.P +.PD +https://github.com/jimsalterjrs/sanoid/ +.SH AUTHORS +zico (\[at]zico:tent.passtheballsocrates.com). diff --git a/suggestions.md b/suggestions.md index 0d666be..a3e5365 100644 --- a/suggestions.md +++ b/suggestions.md @@ -1,15 +1,13 @@ -# Suggestions for setting up your backup account -Author: zico (@zico:tent.passtheballsocrates.com) -## Contents -* Basic Intro -* How to use your account -* Backup Software -* ZFS +--- +title: Suggestions for setting up your backup account +author: +- zico (@zico:tent.passtheballsocrates.com) +--- -## Basic Intro +# Introduction Hello! Welcome to your LayerZero members-only bonus premium backup server! I (zico) set this up to have a remote backup for myself and to offer this to -the wonderful (and less-wonderful) people of LZ. +the wonderful people of Cyberia Computer Club. As you probably know by being able to read this file, the server is set up where each user gets a shell account with ssh access. Each account has the same quota @@ -21,7 +19,7 @@ The server is encrypted at rest (when the power is off, essentially), including all the home directories. You are also encouraged to encrypt your files yourself with tools like restic, borg, rsync, or the included zfs. -## How to use your account +# How to use your account This server is intended to be for personal backups. A place where you can store your precious cat pics, secret documents, and traditional family hotdish recipes. Although this is a shell account, please don't use this to run services @@ -33,19 +31,20 @@ is available to you! Most backup software these days can use ssh as a backend, and almost all of the tried and true cli methods can too. The accounts themselves are reasonably locked-down, and by design allow you to -throw bits into the filesystem and not much else. I've very open to suggestions +throw bits into the filesystem and not much else. I'm very open to suggestions on how to make this a better experience for people, so please ping me if this model isn't working for what you want to do. -## Backup Software +# Backup Software There is no one best backup software, and this server doesn't prefer one in particular. As long as it can use ssh, it will work with your shell account. Here are some suggestions, organized into cli and gui. -###CLI Backup Softare + +## CLI Backup Softare * rsync - tried and true - flexible and has a million examples on the internet - - fewer nice features like built-in encryption + - lacking some nice features like built-in encryption * rsnapshot - based on rsync, but more oriented towards backups - uses a config file @@ -62,7 +61,8 @@ Here are some suggestions, organized into cli and gui. - see zfs section * sanoid/syncoid - see zfs section -### GUI backup software + +## GUI backup software * Duplicati - WebUI - can be very simple or very complex, depending on your usecase @@ -75,15 +75,15 @@ Here are some suggestions, organized into cli and gui. There are many many backup software solutions. If you need help finding one that works for you, please reach out to me and I'd be happy to help you. -## ZFS +# ZFS ZFS is a weird and wonderful kind of filesystem that incorporates both the actual low-level regular file system stuff and the tools to manage it into one piece of software. If you haven't used it before, it will probably be a bit strange at first. For an introduction to ZFS terms and concepts, this article by Jim Salter is an -excellent resource: - - https://web.archive.org/web/20220902082642/https://arstechnica.com/information-technology/2020/05/zfs-101-understanding-zfs-storage-and-performance/ +excellent resource: +https://web.archive.org/web/20220902082642/https://arstechnica.com/information-technology/2020/05/zfs-101-understanding-zfs-storage-and-performance/ Your access to ZFS on this system is somewhat limited to interacting with your home directory. You have the necessary permissions to create and destroy new @@ -94,13 +94,13 @@ to find out what they mean). There are technically two versions of zfs, the "original" Oracle zfs that they acquired with the takeover of Sun Microsystems, and the OpenZFS version -developed collaberatively accross many people and companies. Almost every -deployment in the wild is the OpenZFSversion, and there are small but -substantial differences between the two.That being said, most of the Oracle zfs +developed collaboratively by many people across many companies. Almost every +deployment in the wild is the OpenZFS version, and there are small but +substantial differences between the two. That being said, most of the Oracle zfs docs come up first when you search for info, and they can generally be used for OpenZFS as well. This server uses the OpenZFS version. -### zfs send/receive +## zfs send/receive This is the native zfs way to move copies of filesystems around. If you've worked with databases before, it's somewhat similar to a dump and restore operation. The basic concept is that you (or an automated tool) take a snapshot @@ -117,15 +117,17 @@ not the actualy file contents. Other backup solutions have similar solutions, but are not as fast as they are not low-level filesystems. Using zfs send/receive for simple cases is pretty simple. For example: -``` + +```sh $ zfs snapshot zroot/home/zico@snapshot1 $ zfs send zroot/home/zico@snapshot1 | ssh zico@backupserver zfs receive backup-pool/home ``` -The Oracle ZFS docs on send/receive are pretty good and are useful for the -OpenZFS version as well. You can find them here: - - https://docs.oracle.com/cd/E18752_01/html/819-5461/gbchx.html -### sanoid/syncoid +The Oracle ZFS docs on send/receive are pretty good and are useful for the +OpenZFS version as well: +https://docs.oracle.com/cd/E18752_01/html/819-5461/gbchx.html + +## sanoid/syncoid "Sanoid is a policy-driven snapshot management tool for ZFS filesystems", according to the github readme. It's one of many zfs send management tools, and it's the one I'm most familiar with. Sanoid allows you to set a config file for @@ -134,5 +136,5 @@ keep them. The companion tool Syncoid will send snapshots of your configured filesystems to another zfs pool, whether that's on the same computer or a remote server like this one. It's a very handy tool to automate zfs backups. -Sanoid and syncoid can be found at their github page: - - https://github.com/jimsalterjrs/sanoid/ +Sanoid and syncoid can be found at their github page: +https://github.com/jimsalterjrs/sanoid/ -- 2.45.2