(no commit message)

[ikiwiki.git] / docs / handbook / handbook-disk-organization.mdwn

## Disk Organization 



The smallest unit of organization that DragonFly uses to find files is the filename. Filenames are case-sensitive, which means that `readme.txt` and `README.TXT` are two separate files. DragonFly does not use the extension (`.txt`) of a file to determine whether the file is a program, or a document, or some other form of data.



Files are stored in directories.  A directory may contain no files, or it may contain many hundreds of files.  A directory can also contain other directories, allowing you to build up a hierarchy of directories within one another.  This makes it much easier to organize your data.



Files and directories are referenced by giving the file or directory name, followed by a forward slash, `/`, followed by any other directory names that are necessary.  If you have directory `foo`, which contains directory `bar`, which contains the file `readme.txt`, then the full name, or ***path*** to the file is `foo/bar/readme.txt`.



Directories and files are stored in a file system. Each file system contains exactly one directory at the very top level, called the ***root directory*** for that file system.  This root directory can then contain other directories.



So far this is probably similar to any other operating system you may have used.  There are a few differences; for example, MS-DOS® uses `\` to separate file and directory names, while Mac OS® uses `:`.



DragonFly does not use drive letters, or other drive names in the path. You would not write `c:/foo/bar/readme.txt` on DragonFly.



Instead, one file system is designated the ***root file system***.  The root file system's root directory is referred to as `/`.  Every other file system is then ***mounted*** under the root file system. No matter how many disks you have on your DragonFly system, every directory appears to be part of the same disk.



Suppose you have three file systems, called `A`, `B`, and `C`. Each file system has one root directory, which contains two other directories, called `A1`, `A2` (and likewise `B1`, `B2` and `C1`, `C2`).



Call `A` the root file system. If you used the `ls` command to view the contents of this directory you would see two subdirectories, `A1` and `A2`.  The directory tree looks like this:



install/example-dir1.png



A file system must be mounted on to a directory in another file system. So now suppose that you mount file system `B` on to the directory `A1`.  The root directory of `B` replaces `A1`, and the directories in `B` appear accordingly:



install/example-dir2.png



Any files that are in the `B1` or `B2` directories can be reached with the path `/A1/B1` or `/A1/B2` as necessary. Any files that were in `/A1` have been temporarily hidden.  They will reappear if `B` is ***unmounted*** from A.



If `B` had been mounted on `A2` then the diagram would look like this:



install/example-dir3.png



and the paths would be `/A2/B1` and `/A2/B2` respectively.



File systems can be mounted on top of one another.  Continuing the last example, the `C` file system could be mounted on top of the `B1` directory in the `B` file system, leading to this arrangement:



install/example-dir4.png



Or `C` could be mounted directly on to the `A` file system, under the `A1` directory:



install/example-dir5.png



If you are familiar with MS-DOS, this is similar, although not identical, to the `join` command.





### Choosing File System Layout 



This is not normally something you need to concern yourself with. Typically you create file systems when installing DragonFly and decide where to mount them, and then never change them unless you add a new disk.



It is entirely possible to have one large root file system, and not need to create any others. There are some drawbacks to this approach, and one advantage.



 **Benefits of Multiple File Systems** 




* Different file systems can have different ***mount options***.  For example, with careful planning, the root file system can be mounted read-only, making it impossible for you to inadvertently delete or edit a critical file.  Separating user-writable file systems, such as `/home`, from other file systems also allows them to be mounted ***nosuid***; this option prevents the ***suid***/***guid*** bits on executables stored on the file system from taking effect, possibly improving security.


* The UFS file system automatically optimizes the layout of files, depending on how the file system is being used. So a file system that contains many small files that are written frequently will have a different optimization to one that contains fewer, larger files.  By having one big file system this optimization breaks down.


* DragonFly's file systems are very robust should you lose power.  However, a power loss at a critical point could still damage the structure of the file system.  By splitting your data over multiple file systems it is more likely that the system will still come up, making it easier for you to restore from backup as necessary. This a major reason to make the root file system of limited size, and with low write activity.



 **Benefit of a Single File System** 




* 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&section8) command makes it possible to increase the size of a UFS file system on the fly.





### Disk Slices, Partitions and local UNIX file systems 

Here we describe how disks are subdivided.



#### Slices 

A disk can be subdivided in slices.

Slices are named `s0`, `s1` and so on.

For examples the disk `ad6` can contain the slice `ad6s3`.

DragonFly support two schemes for slices, MBR and GPT, either of them will manage all slices on a disk:


* MBR: set up using [fdisk(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=fdisk&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.


* GPT: set up using [gpt(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=gpt&section8), can be extremely large: size up to 8 billion TB.  DragonFly doesn't support booting from a GPT slice in DragonFly  2.0.  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&section=8).



#### Partitions 

Partitions are contained in slices.

Partitions are named `a`, `b` and so on.

DragonFly support 16 partitions per slice, that is `a` through `p`.

For example the partition `ad6s3a` is contained in the slice `ad6s3`.

Partitions layout is defined in a label on the slice where the partition reside. DragonFly support two types of disk labels, disklabel and disklabel64:


* [disklabel(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=disklabel&section8): 32 bit disk label which can use slices with size up to 2 TB.


* [disklabel64(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=disklabel64&section8): 64 bit disk label which can use very large slices: size up to 16 million TB. DragonFly doesn't support booting from file systems in these partitions yet.



#### 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&section5), it supports size up to 2 TB.


* [HAMMER(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=HAMMER&section5): A new file system, as of DragonFly 2.0, with many advanced features.  HAMMER file system support size up to 1 million TB.  DragonFly doesn't support booting from a HAMMER file system yet.



#### Typical disk layout 

From the above we see the following typical disk layout scenarios:


* For booting DragonFly from a local file system UFS needs to be used, it will have to reside in a partiton on a [disklabel(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#disklabel&section8) label, which for DragonFly 2.0 needs to be set up on an MBR slice.


* 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&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&section=8).





#### HAMMER Note 

[HAMMER(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=HAMMER&section5)

is a rather new file system, under active development.

As of DragonFly 2.0 HAMMER is considered to be in an early Beta state.

You should evaluate if HAMMER is suitable for your needs.



Examples of ongoing development includes:


* 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&section8) jobs for this yourself, see [hammer(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=hammer&section=8).


* Multi master mirroring. For now only one mirror master is supported, but multiple mirror targets, called slaves, are already supported.


* Support for growing and shrinking existing HAMMER file systems, e.g. by adding and removing volumes from the file system.  The HAMMER design is prepared for this, utilities just have to be written to support it.



#### HAMMER Features 

[HAMMER(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=HAMMER&section5)

has several advanced features not found in UFS:


* Large file systems:  Up to 1 million TB, also called 1 Exabyte is supported.


* 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.


* 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.


* Full history retension:  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 a file is 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: '@@<TID>file'.  The TID can be saved from the '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:  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:  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.



More info on HAMMER can be found [here](http://www.dragonflybsd.org/hammer/index.shtml).



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.





### Adding a Disk 



Adding a disk is done by installing it physically, and to connect it to a disk controller that DragonFly supports.  If you are in doubt if controller is supported, manual pages for disk controllers can be consulted ('man -k disk' or 'man -k scsi' can be of help).  The easiest thing is normally to boot DargonFly with the controller installed and note if boot message contains the controller.



Assuming that disk `ad6` is installed, we could set it up using

[fdisk(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=fdisk&amp;section8) &

[disklabel(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=disklabel&amp;section8)

disklabel or

[gpt(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=gpt&amp;section8) &

[disklabel64(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=disklabel64&amp;section8).  The last option is needed if disk is over 2 TB in size (for 512B block size), but it won't support booting from disk. In this example it is second disk in system so booting from it isn't essential, we choose [gpt(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=gpt&amp;section=8) & [disklabel64(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=disklabel64&amp;section=8).



    

    # gpt -v create ad6

    ...

    # gpt add -s1 ad6

    ad6s0

    # gpt add ad6

    ad6s1

    # gpt show ad6

    ...





Here we first create the GPT and then add two slices.  In this example the first slice added is `ad6s0`, which is made a dummy slice of size 1 sector, this is just for not having to make further reference to it, as many users remembers that `s0` has special meaning, which really isn't true for GPT slices.  The second slice is `ad6s1` which will cover the rest of the disk.



    

    # disklabel64 -rw ad6s1 auto

    # disklabel64 -e ad6s1          # edit label to add partitions as needed





### disklabel 



For [disklabel(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=disklabel&amp;section8) labels some partitions have certain conventions associated with them.



[[!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. 
 `d` | Partition `d` used to have a special meaning associated with it, although that is now gone.  To this day, some tools may operate oddly if told to work on partition `d`. |

"""]]

Each partition-that-contains-a-file-system is stored in what DragonFly calls a ***slice***.  Slice is DragonFly's term for what the common call partitions, and again, this is because of DragonFly's UNIX background.  Slices are numbered, starting at 1, through to 4.



Slice numbers follow the device name, prefixed with an `s`, starting at 1. So ***da0s1*** is the first slice on the first SCSI drive. There can only be four physical slices on a disk, but you can have logical slices inside physical slices of the appropriate type.  These extended slices are numbered starting at 5, so ***ad0s5*** is the first extended slice on the first IDE disk. These devices are used by file systems that expect to occupy a slice.

***Dangerously dedicated*** physical drives are accessed as slice 0.



Slices, ***dangerously dedicated*** physical drives, and other drives contain ***partitions***, which are represented as letters from `a` to `p`.  This letter is appended to the device name, so ***da0s0a*** is the a partition on the first da drive, which is ***dangerously dedicated***. ***ad1s3e*** is the fifth partition in the third slice of the second IDE disk drive.



Finally, each disk on the system is identified.  A disk name starts with a code that indicates the type of disk, and then a number, indicating which disk it is.  Disk numbering starts at 0. Common codes that you will see are listed in [Table 3-1](disk-organization.html#BASICS-DEV-CODES).



When referring to a partition DragonFly requires that you also name the slice and disk that contains the partition, and when referring to a slice you should also refer to the disk name. Do this by listing the disk name, `s`, the slice number, and then the partition letter.  Examples are shown in [Example 3-1](disk-organization.html#BASICS-DISK-SLICE-PART).



[Example 3-2](disk-organization.html#BASICS-CONCEPT-DISK-MODEL) shows a conceptual model of the disk layout that should help make things clearer.



In order to install DragonFly you must first configure the disk slices, then create partitions within the slice you will use for DragonFly, and then create a file system (or swap space) in each partition, and decide where that file system will be mounted.



***'Table 3-1. Disk Device Codes***'



[[!table  data="""
|<tablestyle="width:100%"> Code | Meaning 
<tablestyle="width:100%"> `ad` | ATAPI (IDE) disk 
 `da` | SCSI direct access disk 
 `acd` | ATAPI (IDE) CDROM 
 `cd` | SCSI CDROM 
 `fd` | Floppy disk |

"""]]

***'Example 3-1. Sample Disk, Slice, and Partition Names***'



[[!table  data="""
|<tablestyle="width:100%"> Name | Meaning 
<tablestyle="width:100%"> `ad0s1a` | The first partition (`a`) on the first slice (`s1`) on the first IDE disk (`ad0`). 
 `da1s2e` | The fifth partition (`e`) on the second slice (`s2`) on the second SCSI disk (`da1`). |

"""]]

***'Example 3-2. Conceptual Model of a Disk***'



This diagram shows DragonFly's view of the first IDE disk attached to the system. Assume that the disk is 4 GB in size, and contains two 2 GB slices (MS-DOS partitions).  The first slice contains a MS-DOS disk, `C:`, and the second slice contains a DragonFly installation. This example DragonFly installation has three partitions, and a swap partition.



The three partitions will each hold a file system. Partition `a` will be used for the root file system, `e` for the `/var` directory hierarchy, and `f` for the `/usr` directory hierarchy.



install/disk-layout.png







CategoryHandbook

CategoryHandbook-basics