Edited for readability and content
authornmatavka <nmatavka@web>
Mon, 20 Jan 2014 02:03:38 +0000 (02:03 +0000)
committerCharlie Root <root@leaf.dragonflybsd.org>
Mon, 20 Jan 2014 02:03:38 +0000 (02:03 +0000)
docs/newhandbook/UnixBasics/index.mdwn

index 317f81d..705d1f6 100644 (file)
@@ -347,8 +347,8 @@ It is entirely possible to have one large root file system, and not need to crea
 
 * File systems are a fixed size. If you create a file system when you install DragonFly and give it a specific size, you may later discover that you need to make the partition bigger.  The [growfs(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=growfs&amp;section8) command makes it possible to increase the size of a UFS file system on the fly.
 <!-- XXX: what about hammer? -->
-
 ## Disk Slices, Partitions and local UNIX file systems 
+*** Heavily edited by Nick Matavka***
 
 Here we describe how disks are subdivided.
 
@@ -356,27 +356,25 @@ Here we describe how disks are subdivided.
 
 ### Slices 
 
-A disk can be subdivided in slices.
-
-Slices are named `s0`, `s1` and so on.
+In BSD UNIX, including DragonFly, what are elsewhere known as ***partitions*** are instead known as ***slices***; on a multi-boot system, every operating system occupies at least one slice and is aware of the others.  Linux, and most UNIX operating systems, generally occupy at least two slices, one for the file system and one for swap space; on the other hand, BSD (with the exception of MacOS/DarwinBSD) may occupy only one slice, using an alternative method (called ***partitioning*** in BSD) to segregate file system and swap space.  Programs such as `parted` and `gparted`, contrary to their names, are in fact disk slicers.
 
-For example the disk `ad6` can contain the slice `ad6s3`.
+In DragonFly, disk slices are designated with the letter `s` for ***slice*** and a positive integer, beginning either from zero or one, depending on the slicing scheme.  The first slice of a physical disk is thus named `s0`; the second, `s1`; and so on.  There can only be four ***physical*** slices on a disk, but one of these, designated the ***extended*** slice, may itself be sliced into ***logical*** slices.  If an extended slice exists, the logical slices it contains are numbered beginning with `s5`.  
 
-DragonFly supports two schemes for slices, MBR and GPT.  Either of them will manage all slices on a disk:
+For instance, the disk `ad6` may be divided into physical slices `ad6s1`, `ad6s2` (the extended slice, containing logical slices `ad6s5` and `ad6s6`), and `ad6s3`.  Note that if there are less than four physical slices, the relevant numbers are skipped, even if there are logical slices.
 
-* MBR: set up using [fdisk(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=fdisk&amp;section8), can be up to 2 TB in size.  MBR slices are numbered from 1; but if disk is ***dangerously dedicated*** it has slice number 0.
+DragonFly support two schemes for slices, MBR and GPT. Either of them can manage all of the slices on a disk:
 
-* GPT: set up using [gpt(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=gpt&amp;section8), can be extremely large: size up to 8 billion TB.  DragonFly doesn't support booting from a GPT slice in DragonFly  2.0.  Note that GPT slices are numbered from 0. ***Dangerously dedicated*** is not supported nor needed for GPT.  DragonFly 2.1 does have some support for booting from a GPT slice, this is described in [gpt(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=gpt&amp;section=8).
+* MBR: are set up using [fdisk(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=fdisk&amp;section8) and can be up to two terabytes (2,048 GB) in size.  Usually, MBR slices are numbered from 1; if there is only one slice on the disk (that is, the disk is ***dangerously dedicated***), however,it has slice number 0.
 
-### Partitions 
+* GPT: are set up using [gpt(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=gpt&amp;section8) and support disk sizes up to eight exabytes (eight billion terabytes, a ludicrously large and, within the foreseeable future, entirely theoretical size equivalent to 800,000 times the sum total of printed works within the Library of Congress).  ***Dangerous dedication*** is irrelevant in GPT; slices are ***always*** numbered from 0.
 
-Partitions are contained in slices.
+***NOTE:*** DragonFly doesn't support booting from a GPT slice in DragonFly  2.0.  DragonFly 2.1 does have some support for booting from a GPT slice, this is described in [gpt(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=gpt&amp;section=8).
 
-Partitions are named `a`, `b` and so on.
+### Partitions 
 
-DragonFly support 16 partitions per slice, that is `a` through `p`.
+Uniquely in BSD, disk slices contain `disklabel` partitions, not to be confused with the word partition in its usual meaning (that kind of partition is called a slice in BSD).  In most variants of UNIX, at least two slices are used to contain the system: one for the primary file system, and one for swap space.  With one exception, BSD can dispense with slices entirely and use a utility known as `disklabel` (or `bsdlabel`) to ***partition*** the disk instead. 
 
-For example the partition `ad6s3a` is contained in the slice `ad6s3`.
+All BSD UNIX operating systems support eight partitions per slice, labelled `a` through `h`; most BSD systems, DragonFly included, support an additional eight, labelled `i` through `p`, for a total of sixteen per slice.  Partition layout is defined in a label on the slice where they reside.  Since each partition may have its own ***file system***, ***in BSD***, one slice may be formatted in several different file systems (a situation that does not hold true in Linux or Windows). 
 
 Partition layout is defined in a label on the slice where the partition reside. DragonFly support two types of disk labels, disklabel32 and disklabel64 (the default):
 
@@ -384,71 +382,57 @@ Partition layout is defined in a label on the slice where the partition reside.
 
 * [disklabel64(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=disklabel64&amp;section8): 64 bit disk label which can use very large slices: size up to 16 million TB.
 
-### Local UNIX file systems 
-
-File systems are contained in partitions.  Each partition can contain only one file system, which means that file systems often are described by either their typical mount point in the file system hierarchy, or the letter of the partition they are contained in.  ***Partition*** does not have the same meaning as the common usage of the term partition (for example, MS-DOS partition), because of DragonFly's UNIX┬« heritage.
-
-DragonFly support two local UNIX file systems, UFS and HAMMER:
-
-* UFS: The classical BSD UNIX file system, see [ffs(5)](http://leaf.dragonflybsd.org/cgi/web-man?command#ffs&amp;section5), it supports size up to 2 TB.
-
-* [HAMMER(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=HAMMER&amp;section5): A new file system, as of DragonFly 2.0, with many advanced features.  HAMMER file system support size up to 1 million TB.
-
-### Typical disk layout 
+***By convention***, four partition labels are reserved by the system and have special meanings.  The convention does not strictly have to hold true, but it is highly recommended to follow this gentleman's agreement:
 
-From the above we see the following typical disk layout scenarios:
-
-* For booting DragonFly from a local file system UFS is recommended.  A BOOT+HAMMER setup is recommended for HAMMER use, this consists of a small UFS file system for booting, typically 512MB, and a HAMMER root file system.  The BOOT file system is mounted as /boot after boot.
-
-* For moderate storage requirements UFS can be used; it can be setup on any partition, e.g. on the same disk slice as the boot partition.  HAMMER is an alternative, with extra features supported, like history retention.  You should evaluate if HAMMER is suitable, see note below.
-
-* If really big storage capacity is needed UFS can't fit the need.  You should evaluate if HAMMER is suitable, see note below.  For this use HAMMER needs to be used on a GPT slice with  a [disklabel64(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=disklabel64&amp;section8) label.  In DragonFly 2.0 it has to be set up on a disk separate from the boot disk.  In  DragonFly 2.1 one disk can be used for both booting and HAMMER file system on GPT slice, as some support for booting from GPT is present, as described in [gpt(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=gpt&amp;section=8).
-
-### HAMMER Note 
+[[!table  data="""
+<tablestyle="width:100%"> Partition | Convention 
+<tablestyle="width:100%"> `a` | Normally contains the root file system 
+ `b` | Normally contains swap space 
+  `c` | Normally the same size as the enclosing slice.  This allows utilities that need to work on the entire slice (for example, a bad block scanner) to work on the `c` partition. You would not normally create a file system on this partition. This is not necessarily true; it is possible to use the 'c' partition as a normal partition.
+   `d` | Normally the same size as the entire physical disk.  This is now rare, but to this day, some tools may operate oddly if told to work on partition `d`. |
 
-[HAMMER(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=HAMMER&amp;section5)
+   """]]
 
-is a rather new file system, under active development.
+   
 
-As of DragonFly 2.2.1 release HAMMER is considered production ready.  At 2.0 release it was considered to be in an early Beta state .
+### Local UNIX file systems 
 
-All major features except the mirroring are quite well tested as-of the 2.2.1 release.
+Each partition can contain only one ***file system***. Therefore, file systems often are described by either their typical mount point in the file system hierarchy, or the letter of the `disklabel` partition they are contained in.  DragonFly BSD supports two local UNIX file systems, UFS and HAMMER:
 
-You should evaluate if HAMMER is suitable for your needs.
-<!-- XXX: mention disk and memory requirements for efficient hammer use -->
+* UFS: is the classic BSD UNIX file system (see [ffs(5)](http://leaf.dragonflybsd.org/cgi/web-man?command#ffs&amp;section5)). It supports a volume size up to two terabytes.
 
-Examples of ongoing development includes:
+* [HAMMER(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=HAMMER&amp;section5): introduced in DragonFly 2.0, this is a new file system with many advanced features.  HAMMERfs supports a volume size of up to one exabyte (one million terabytes).
 
-* Making HAMMER more self managing; e.g. ability to setup policy for which history to save for how long: e.g. make snapshot every hour and prune and reblock the file system regularly.  When snapshot gets older than 1 month only keep them for every 6 hours; when older than 3 months only keep snapshot for every 24 hours, when older than 3 years only keep snapshot per month.  For now you need to set up [cron(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=cron&amp;section8) jobs for this yourself, see [hammer(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=hammer&amp;section=8).
+***Historically***, the desirability of HAMMERfs increased with storage capacity.  For booting DragonFly from a small, local file system, UFS was previously recommended, with the option of a BOOT+HAMMER set up (512 MB UFS boot partition, the rest HAMMERfs).  For moderate storage requirements, UFS continued to be an option, but the extra features boasted by HAMMERfs (such as history retention) made it more desirable in this regard.  
+Then, as now, HAMMERfs was the unrivalled king of the large partition, usually with a [disklabel64(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=disklabel64&amp;section8) label on a GPT slice.
 
-* Multi master mirroring. For now only one mirror master is supported, but multiple mirror targets, called slaves, are already supported.
+As of DragonFly version 3.6, this question is mostly, or entirely, of academic interest. HAMMERfs is now recommended for all volumes greater than eighty gigabytes---that is to say, all volumes manufactured within the last five years, and a goodly portion of older ones as well.
 
-* Support for shrinking existing HAMMER file systems.  The HAMMER design is prepared for this, utility just have to be written to support it.
-<!-- XXX: is this still accurate? Do we really want to mention it here? -->
+## The HAMMER File System
 
-### HAMMER Features 
+[HAMMER(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=HAMMER&amp;section5) is a rather new file system, under active development.  HAMMERfs reached beta in release 2.0.  As of release 2.2.1, HAMMERfs is considered to be appropriate for use in the production environment; DragonFly is currently in release 3.6.    
 
-[HAMMER(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=HAMMER&amp;section5) has several advanced features not found in UFS:
+If you are deploying DragonFly on a low-capacity, low-memory system, you should evaluate if HAMMERfs is suitable for your needs; for a personal computer or server of even medium vintage, no thought need go into this, as it will be found that HAMMERfs is the file system ***of choice***.  [HAMMER(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=HAMMER&amp;section5) has several advanced features not found in UFS:
 
-* Large file systems:  Up to 1 million TB, also called 1 Exabyte is supported.
+* Large file systems:  HAMMERfs supports systems up to one exabyte (that is, one million terabytes) in size. 
 
-* Multiple volumes:  A HAMMER file system can span up to 256 disks, each partition part of a HAMMER file system is called a volume.  Each volume can be up to 4096 TB in size.
+* Multiple volumes: A HAMMER file system can span up to 256 disks.  Each part of a HAMMER file system is called a volume; each volume can be up to 4096 TB in size.
 
-* Support for growing and shrinking existing HAMMER file systems: adding and removing volumes from the file system.  As of 2.4 release an existing HAMMER file system can be expanded by adding extra space, see the `expand` directive to [hammer(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=hammer&amp;section=8).  The HAMMER design is also prepared for removing volumes, utilities just have to be written to support it.
+* Re-sizeability: As of release 2.4, the `expand` directive to [hammer(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=hammer&amp;section=8) allows HAMMER file systems to be easily re-sized; volumes may also be added and removed.  
 
-* Instant crash recovery:  If a crash should occur, then HAMMER file systems will be ready a few seconds after boot, no lenghty fsck have to be run.
+* Instant crash recovery:  Should a crash occur, HAMMER obviates the necessity for `fsck`, saving precious time in mission-critical applications. 
 
-* Full history retention:  All file system changes are saved every ~30 seconds.  Changes are written at least when sync() is called, see [syncer(4)](http://leaf.dragonflybsd.org/cgi/web-man?command=syncer&amp;section4).  Every time data for files are written to disk a transaction is completed, this is assigned an ID and the file updated can after this be accessed with the contents from this moment.  To access the file with the state of this moment, the transaction ID, TID for brevity, just needs to be added to the file name, like: 'file@@<TID>'.  The TID can be saved from the 'snapshot', 'cleanup', or 'synctid' [hammer(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=hammer&amp;section=8) command or looked up with the 'hammer history file' command.  This history will typically grow over time, so any disk will fill up over time.  Two things are done so disks doesn't fill up: first: big disks are used, at least 50GB is typical for HAMMER file systems, and second: unused history information is deleted regularly. Here we need to define what unused means: a TID is used if a snapshot have been taken on it. Data assigned to unused history can be reclaimed using the `prune` and `reblock` [hammer(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=hammer&amp;section=8) commands, this will also defragment the file system and can be done while the file system is in normal operation.  Generally after file system is pruned only TIDs for the snapshots or newer than newest shapshot should be used, see explanation [here](http://leaf.dragonflybsd.org/mailarchive/bugs/2008-07/msg00213.html) (more info on HAMMER design [here](http://leaf.dragonflybsd.org/mailarchive/kernel/2008-07/msg00114.html)).  See also [hammer(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=hammer&amp;section=5). 
+* Mirroring:  HAMMERfs makes it possible to ***mirror*** a master file system to a number of slave file systems.  Although mirror targets are, by necessity, read-only, they do have history available.  The history retention policy can even be different on slaves and master. Mirroring over network is supported, and unreliable connections are handled gracefully.
 
-* Mirroring:  A master file system can be mirrored online to a number of slave file systems.  Mirror targets are read-only, but does have history available.  History retension policy can even be different on slaves and master.  Mirroring can be over network and unreliable connections are handled gracefully.
+* Data integrity:  HAMMERfs makes data integrity a priority by implementing cyclic redundancy checks on all data.  If bits become corrupted, this will be detected.
 
-* Data integrity:  HAMMER has high focus in data integrity and implements a CRC checksum on all data, this means that if disk fails with bit errors it will be detected.
+All these features are subordinate to the single, basic, overarching purpose of the HAMMER file system: ***full history retention***.  With HAMMERfs, **all** file system changes are saved every ~30 seconds.  Changes are written at least when sync() is called (see [syncer(4)](http://leaf.dragonflybsd.org/cgi/web-man?command=syncer&amp;section4)).  Every time data are written to disk, a transaction is completed, this is assigned an identifier,  and the file updated can after this be accessed with the contents from this moment.  
 
-More info on HAMMER can be found [here](http://www.dragonflybsd.org/hammer/index.html).
+To access the file as it was then, all the user must do is add the transaction identifier to the file name, in the form `file@@<tid>`.  The TID can be saved from the `snapshot`, `cleanup`, or `synctid` [hammer(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=hammer&amp;section=8) command, or looked up with the `hammer history file` command.  This history will typically grow over time, so any disk will fill up over time.  
 
-DragonFly also uses disk space for ***swap space***.  Swap space provides DragonFly with ***virtual memory***.  This allows your computer to behave as though it has much more memory than it actually does.  When DragonFly runs low on memory it moves some of the data that is not currently being used to the swap space, and moves it back in (moving something else out) when it needs it.
+Two things are done so the disk does not fill up too fast, or too much.  First of all, at least moderately large disks are used.  Second, HAMMER can be made self-managing with a policy for which history to save for how long.  For example, make a snapshot every hour and `prune` and `reblock` ([hammer(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=hammer&amp;section=8)) regularly.  When snapshots get older than one month, keep them for six hours; when older than three months, keep them for a day; when older than  three years, keep them for a month. 
 
-<!-- XXX: mention swapcache, and also how to configure and use it (somewhere else, probably) -->
+Historically, you needed to set up  [cron(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=cron&amp;section8) jobs for this yourself, but HAMMER now includes a utility to make this easy.
 
 ### Adding a Disk