From 7d28570290edd54a5667f2cde2217e5342bfbd6f Mon Sep 17 00:00:00 2001 From: Koen Vervloesem Date: Mon, 3 Jun 2019 17:55:53 +0200 Subject: [PATCH] Documentation fixes: typos, links, whitespace --- docs/applications/bitwarden.md | 4 ++-- docs/applications/firefly.md | 2 +- docs/applications/mymediaforalexa.md | 2 +- docs/applications/nzbget.md | 2 +- docs/applications/transmission.md | 4 ++-- docs/applications/watchtower.md | 4 ++-- docs/configuration/external_access.md | 2 +- docs/hardware.md | 4 ++-- docs/index.md | 4 ++-- docs/overview.md | 16 ++++++++-------- docs/post_installation.md | 4 ++-- docs/zfs/zfs_configuration.md | 6 +++--- docs/zfs/zfs_overview.md | 12 ++++++------ 13 files changed, 33 insertions(+), 33 deletions(-) diff --git a/docs/applications/bitwarden.md b/docs/applications/bitwarden.md index 4511bac9..5cfc0ae6 100644 --- a/docs/applications/bitwarden.md +++ b/docs/applications/bitwarden.md @@ -11,10 +11,10 @@ Set `bitwarden_enabled: true` in your `group_vars/all.yml` file. ## Specific Configuration -Make sure you set your admin token! It is `bitwarden_admin_token` in `group_vars/all.yml` file. The string you put here will be the login to the admin section of your bitwarden installation (https://bitwarden.ansiblenasdomain.tld/admin). This token can be anything, but it's recommended to use a long, randomly generated string of characters, for example running: +Make sure you set your admin token! It is `bitwarden_admin_token` in `group_vars/all.yml` file. The string you put here will be the login to the admin section of your Bitwarden installation (https://bitwarden.ansiblenasdomain.tld/admin). This token can be anything, but it's recommended to use a long, randomly generated string of characters, for example running: `openssl rand -base64 48`. To create a user, you need to set `bitwarden_allow_signups` to `true` in your `all.yml`, and re-run the playbook to reprovision the container. Once you've created your users, set `bitwarden_allow_signups` back to `false` and run again. -For speed you can target just Bitwarden by appending `-t bitwarden` to your `ansible-playbook` command. \ No newline at end of file +For speed you can target just Bitwarden by appending `-t bitwarden` to your `ansible-playbook` command. diff --git a/docs/applications/firefly.md b/docs/applications/firefly.md index 3a8a843e..d7a8ee3e 100644 --- a/docs/applications/firefly.md +++ b/docs/applications/firefly.md @@ -8,4 +8,4 @@ Firefly III is a self-hosted financial manager. It can help you keep track of ex Set `firefly_enabled: true` in your `group_vars/all.yml` file. -The very basic MiniDLNA web interface can be found at http://ansible_nas_host_or_ip:8066. +The Firefly III web interface can be found at http://ansible_nas_host_or_ip:8066. diff --git a/docs/applications/mymediaforalexa.md b/docs/applications/mymediaforalexa.md index 927ee2f6..fe34eb71 100644 --- a/docs/applications/mymediaforalexa.md +++ b/docs/applications/mymediaforalexa.md @@ -1,6 +1,6 @@ # My Media for Alexa -Homepage: https://www.mymediaalexa.com/](https://www.mymediaalexa.com/) +Homepage: [https://www.mymediaalexa.com/](https://www.mymediaalexa.com/) My Media lets you stream your music collection to your Amazon Echo or Amazon Dot without having to upload all your music collection to the Cloud. This keeps your music under your control. diff --git a/docs/applications/nzbget.md b/docs/applications/nzbget.md index eddd2c4c..d04d152e 100644 --- a/docs/applications/nzbget.md +++ b/docs/applications/nzbget.md @@ -2,7 +2,7 @@ Homepage: [https://nzbget.net/](https://nzbget.net/) -The most efficient usenet downloader. NZBGet is written in C++ and designed with performance in mind to achieve maximum download speed by using very little system resources. +The most efficient Usenet downloader. NZBGet is written in C++ and designed with performance in mind to achieve maximum download speed by using very little system resources. ## Usage diff --git a/docs/applications/transmission.md b/docs/applications/transmission.md index 17811d83..7fed5f63 100644 --- a/docs/applications/transmission.md +++ b/docs/applications/transmission.md @@ -3,7 +3,7 @@ Homepage: [https://transmissionbt.com/](https://transmissionbt.com/) Transmission is a free BitTorrent client. Two versions are provided - one that tunnels through a VPN and one that connects -directly. +directly. ## Usage @@ -13,5 +13,5 @@ Transmission's web interface can be found at http://ansible_nas_host_or_ip:9091 ## Specific Configuration -If you enable Tranmission with OpenVPN, you'll need to copy `group_vars/vpn_credentials.yml.dist` to +If you enable Transmission with OpenVPN, you'll need to copy `group_vars/vpn_credentials.yml.dist` to `group_vars/vpn_credentials.yml` and fill in your settings. diff --git a/docs/applications/watchtower.md b/docs/applications/watchtower.md index 043d2051..516fe30b 100644 --- a/docs/applications/watchtower.md +++ b/docs/applications/watchtower.md @@ -2,7 +2,7 @@ Homepage: [https://github.com/v2tec/watchtower](https://github.com/v2tec/watchtower) -A process for watching your Docker containers and automatically udpating and restarting them whenever their base image is refreshed. +A process for watching your Docker containers and automatically updating and restarting them whenever their base image is refreshed. ## Usage @@ -12,4 +12,4 @@ Set `watchtower_enabled: true` in your `group_vars/all.yml` file. By default Watchtower is configured to check daily at 5am for updates. -Various notification options are available, and can be configured by updating `watchtower_command` in your `group_vars/all.yml` file. A few examples are provided. The full set of options can be found at the [Watchtower GitHub project page](https://github.com/v2tec/watchtower). \ No newline at end of file +Various notification options are available, and can be configured by updating `watchtower_command` in your `group_vars/all.yml` file. A few examples are provided. The full set of options can be found at the [Watchtower GitHub project page](https://github.com/v2tec/watchtower). diff --git a/docs/configuration/external_access.md b/docs/configuration/external_access.md index 9daba0bd..570ced30 100644 --- a/docs/configuration/external_access.md +++ b/docs/configuration/external_access.md @@ -11,7 +11,7 @@ There are a number of steps required to enable external access to the applicatio Enabling access to applications externally **does not** automatically secure them. If you can access an application from within your own network without a username and password, this will also be the case externally. -It is your responsiblity to ensure that applications you enable external access to are secured appropriately! +It is your responsibility to ensure that applications you enable external access to are secured appropriately! ## Enable Traefik diff --git a/docs/hardware.md b/docs/hardware.md index 54066e11..93d082b2 100644 --- a/docs/hardware.md +++ b/docs/hardware.md @@ -16,6 +16,6 @@ The [homeserver Reddit](https://www.reddit.com/r/HomeServer/) has lots of good i ## HP Microserver -Ansible-NAS development is tested against an HP Microserver N54L, with 16GB of memory, a 60gb SSD for the OS and 4x2TB WD Red NAS drives for storage. It works great :-) +Ansible-NAS development is tested against an HP Microserver N54L, with 16GB of memory, a 60GB SSD for the OS and 4x2TB WD Red NAS drives for storage. It works great :-) -This is obviously not the only solution but a reasonable one if you just want a single box to buy, and many different models are available on eBay for varying costs. \ No newline at end of file +This is obviously not the only solution but a reasonable one if you just want a single box to buy, and many different models are available on eBay for varying costs. diff --git a/docs/index.md b/docs/index.md index bb9c232a..0db3041e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -24,8 +24,8 @@ Ansible config and a bunch of Docker containers. Ansible-NAS was born! Head to [installation](installation.md) if you're ready to roll, or to [testing](testing.md) if you want to spin up a test Virtual Machine first. Once -you're done, check out the [post-installation](post_installation.md) steps. +you're done, check out the [post-installation](post_installation.md) steps. If this is all very confusing, there is also an [overview](overview.md) of the project and what is required for complete beginners. If you're only confused -abot ZFS, we'll help you [get started](zfs/zfs_overview.md) as well. +about ZFS, we'll help you [get started](zfs/zfs_overview.md) as well. diff --git a/docs/overview.md b/docs/overview.md index 82808580..40df536b 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -10,14 +10,14 @@ small box that sits in the corner and runs 24/7. These days, a NAS doesn't just only handle files, but also offers other services, for instance video streaming with [Plex](https://www.plex.tv/) or [Emby](https://emby.media/index.html). You can buy consumer NAS boxes from [various -manifacturers](https://en.wikipedia.org/wiki/List_of_NAS_manufacturers) where +manufacturers](https://en.wikipedia.org/wiki/List_of_NAS_manufacturers) where you just have to add the hard drives, or you can configure your own hardware and -use open-source software as the operating system. +use open-source software as the operating system. One example of the second variant you'll see mentioned here is [FreeNAS](https://freenas.org/). It is based on [FreeBSD](https://www.freebsd.org/), which like Linux belongs to the family of -Unix-like operating systems. One strength of FreeBSD/FreeNAS is that it +Unix-like operating systems. One strength of FreeBSD/FreeNAS is that it includes the powerful ZFS file system ([OpenZFS](http://www.open-zfs.org/wiki/Main_Page), to be exact). However, it does not support the [Docker](https://www.docker.com/) containers the way Linux @@ -30,7 +30,7 @@ using Docker on Linux with ZFS. This is possible because the technologies. As the name says, Ansible-NAS uses [Ansible](https://www.ansible.com/) server automation which is usually deployed on big multi-machine enterprise systems, not small home servers the size of a -breadbox. +breadbox. ## Before you take the plunge @@ -38,12 +38,12 @@ The commercial NAS vendors try to make setting up and running a NAS as simple and painless as possible - for a fee, obviously. The open-source NAS software providers have lots of resources to help you get started with your own hardware. FreeNAS for instance comes with extensive documentation, good introductions to -ZFS and other topics, and a large community to lean on. +ZFS and other topics, and a large community to lean on. With Ansible-NAS, at this point at least, you're pretty much on your own. Though there is a [Gitter](https://gitter.im/Ansible-NAS/Chat) chat room (see [support](support.md)), you're expected to have some familiarity with the -technologies involved and be able to set up the basic stuff yourself. +technologies involved and be able to set up the basic stuff yourself. As a to-do list, before you can even install Ansible-NAS, you'll have to: @@ -65,13 +65,13 @@ As a to-do list, before you can even install Ansible-NAS, you'll have to: You will probably want to install a specialized filesystem for bulk storage such as [ZFS](http://www.open-zfs.org/wiki/Main_Page) or [Btrfs](https://btrfs.wiki.kernel.org/index.php/Main_Page). Both offer features -such as snapshots, checksumming and scrubing to protect your data against +such as snapshots, checksumming and scrubbing to protect your data against bitrot, ransomware and other nasties. Ansible-NAS historically prefers **ZFS** because this lets you swap storage pools with [FreeNAS](https://freenas.org/zfs/). A [brief introduction](zfs/zfs_overview.md) to ZFS is included in the Ansible-NAS documentation, as well as [an example](zfs_configuration.md) of a very simple ZFS setup. - + After that, you can continue with the actual [installation](installation.md) of Ansible-NAS. diff --git a/docs/post_installation.md b/docs/post_installation.md index 41e80f25..04ff32d7 100644 --- a/docs/post_installation.md +++ b/docs/post_installation.md @@ -3,7 +3,7 @@ So you've installed Ansible-NAS. Now what? The first thing to do is to configure [Heimdall](https://heimdall.site/) as the dashboard of your new NAS, because most of the applications included come with a web interface. Heimdall lets you create "apps" for them which appear as little -icons on the screen. +icons on the screen. To add applications to Heimdall, you'll need the IP address of your NAS. If you don't know it for some reason, you will have to look up using the console with @@ -15,7 +15,7 @@ device, will show the address. Another alternative is to make sure `ip a` command again. Next, you need the application's port, which you can look up in the [list of -ports](application_ports.md). You can test the combination of address and port +ports](configuration/application_ports.md). You can test the combination of address and port in your browser by typing them joined by a colon. For instance, for Glances on a machine with the IPv4 address 192.168.1.2, the full address would be `http://192.168.1.2:61208`. Once you are sure it works, use this address and diff --git a/docs/zfs/zfs_configuration.md b/docs/zfs/zfs_configuration.md index 7f36f2f3..bea12904 100644 --- a/docs/zfs/zfs_configuration.md +++ b/docs/zfs/zfs_configuration.md @@ -59,14 +59,14 @@ The options from simple to complex are: **NAME**: ZFS pools traditionally take their names from characters in the [The Matrix](https://www.imdb.com/title/tt0133093/fullcredits). The two most common are `tank` and `dozer`. Whatever you use, it should be short - think `ash`, not -`xenomorph`. +`xenomorph`. **DRIVES**: The Linux command `lsblk` will give you a quick overview of the hard drives in the system. However, we don't pass the drive specification in the format `/dev/sde` because this is not persistent. Instead, [always use](https://github.com/zfsonlinux/zfs/wiki/FAQ#selecting-dev-names-when-creating-a-pool) the output of `ls /dev/disk/by-id/` to find the drives' IDs. - + **ASHIFT**: This is required to pass the [sector size](https://github.com/zfsonlinux/zfs/wiki/FAQ#advanced-format-disks) of the drive to ZFS for optimal performance. You might have to do this by hand because @@ -179,7 +179,7 @@ pre-compressed files - should probably take the exact same parameters. ### Downloads For downloads, we can leave most of the default parameters the way they are. - + ``` sudo zfs create tank/downloads sudo zfs set exec=off tank/downloads diff --git a/docs/zfs/zfs_overview.md b/docs/zfs/zfs_overview.md index 9bc9b012..bee4db5e 100644 --- a/docs/zfs/zfs_overview.md +++ b/docs/zfs/zfs_overview.md @@ -12,7 +12,7 @@ manager originally created by Sun Microsystems starting in 2001. First released in 2005 for OpenSolaris, Oracle later bought Sun and switched to developing ZFS as closed source software. An open source fork took the name [OpenZFS](http://www.open-zfs.org/wiki/Main_Page), but is still called "ZFS" for -short. It runs on Linux, FreeBSD, illumos and other platforms. +short. It runs on Linux, FreeBSD, illumos and other platforms. ZFS aims to be the ["last word in filesystems"](https://blogs.oracle.com/bonwick/zfs:-the-last-word-in-filesystems), @@ -65,7 +65,7 @@ Pools do not directly consist of hard disks or SSDs. Instead, drives are organized as **virtual devices** (VDEVs). This is where the physical redundancy in ZFS is located. Drives in a VDEV can be "mirrored" or combined as "RaidZ", roughly the equivalent of RAID5. These VDEVs are then combined into a pool by the -administrator. The command might look something like this: +administrator. The command might look something like this: ``` sudo zpool create tank mirror /dev/sda /dev/sdb @@ -96,7 +96,7 @@ with ransomware, you can simply laugh maniacally and revert to the old version: Of course, you would lose any texts you might have added to the filesystem between that snapshot and now. Usually, you'll have some form of **automatic -snapshot administration** configured. +snapshot administration** configured. To detect bitrot and other data defects, ZFS periodically runs **scrubs**: The system compares the available copies of each data record with their checksums. @@ -130,7 +130,7 @@ wrong. Partially this is because it has been in use for almost 15 years now and things change, partially it is the result of being used on different operating systems which have minor differences under the hood. Also, Google searches tend to first return the Oracle documentation for their closed source ZFS variant, -which is increasingly diverging from the open source OpenZFS standard. +which is increasingly diverging from the open source OpenZFS standard. To clear up some of the most common misunderstandings: @@ -162,7 +162,7 @@ This is another case where a recommendation has been taken as a requirement. To quote the [ZFS on Linux FAQ](https://github.com/zfsonlinux/zfs/wiki/FAQ#do-i-have-to-use-ecc-memory-for-zfs) again: - + > Using ECC memory for OpenZFS is strongly recommended for enterprise > environments where the strongest data integrity guarantees are required. > Without ECC memory rare random bit flips caused by cosmic rays or by faulty @@ -176,7 +176,7 @@ and ZFS is no exception. However, there is absolutely no requirement for ZFS to have ECC RAM. If you just don't care about the danger of random bit flips because, hey, you can always just download [Night of the Living Dead](https://archive.org/details/night_of_the_living_dead) all over again, -you're prefectly free to use normal RAM. If you do use ECC RAM, make sure your +you're perfectly free to use normal RAM. If you do use ECC RAM, make sure your processor and motherboard support it. ### No, the SLOG is not really a write cache