typo fix
[ikiwiki.git] / docs / newhandbook / environmentquickstart / index.mdwn
CommitLineData
85e01a9d 1# DragonFly BSD Quick Start
2This document describes the DragonFly environment one will find on a newly installed system.
7edbed66 3[[!toc levels=3 ]]
4
85e01a9d 5## Disk layout
f8143472 6
85e01a9d 7If you chose to install on the HAMMER file system during installation you will be left with a system with the following disk configuration:
6fc3671b 8
9 # df -h
10 Filesystem Size Used Avail Capacity Mounted on
11 ROOT 288G 12G 276G 4% /
12 devfs 1.0K 1.0K 0B 100% /dev
13 /dev/serno/9VMBWDM1.s1a 756M 138M 558M 20% /boot
14 /pfs/@@-1:00001 288G 12G 276G 4% /var
15 /pfs/@@-1:00002 288G 12G 276G 4% /tmp
16 /pfs/@@-1:00003 288G 12G 276G 4% /usr
17 /pfs/@@-1:00004 288G 12G 276G 4% /home
18 /pfs/@@-1:00005 288G 12G 276G 4% /usr/obj
19 /pfs/@@-1:00006 288G 12G 276G 4% /var/crash
20 /pfs/@@-1:00007 288G 12G 276G 4% /var/tmp
21 procfs 4.0K 4.0K 0B 100% /proc
f8143472 22
23In this example
24
85e01a9d 25* `/dev/serno/9VMBWDM1` is the hard disk specified with serial number,
26* `/dev/serno/9VMBWDM1.s1` is the first slice on the hard disk.
f8143472 27
85e01a9d 28The disklabel looks at follows
f8143472 29
85e01a9d 30 # disklabel /dev/serno/9VMBWDM1.s1
f8143472 31
cfde13a4 32 # /dev/serno/9VMBWDM1.s1:
33 #
34 # Informational fields calculated from the above
35 # All byte equivalent offsets must be aligned
36 #
37 # boot space: 1044992 bytes
38 # data space: 312567643 blocks # 305241.84 MB (320069266944 bytes)
39 #
40 # NOTE: If the partition data base looks odd it may be
41 # physically aligned instead of slice-aligned
42 #
43 diskid: e67030af-d2af-11df-b588-01138fad54f5
44 label:
45 boot2 data base: 0x000000001000
46 partitions data base: 0x000000100200
47 partitions data stop: 0x004a85ad7000
48 backup label: 0x004a85ad7000
49 total size: 0x004a85ad8200 # 305242.84 MB
50 alignment: 4096
51 display block size: 1024 # for partition display only
52
53 16 partitions:
54 # size offset fstype fsuuid
55 a: 786432 0 4.2BSD # 768.000MB
56 b: 8388608 786432 swap # 8192.000MB
57 d: 303392600 9175040 HAMMER # 296281.836MB
58 a-stor_uuid: eb1c8aac-d2af-11df-b588-01138fad54f5
59 b-stor_uuid: eb1c8aec-d2af-11df-b588-01138fad54f5
60 d-stor_uuid: eb1c8b21-d2af-11df-b588-01138fad54f5
61
f8143472 62
a4b3282d 63The slice has 3 partitions:
f8143472 64
85e01a9d 65* `a` - for `/boot`
66* `b` - for swap
67* `d` - for `/`, a HAMMER file system labeled ROOT
f8143472 68
85e01a9d 69When you create a HAMMER file system you must give it a label, here the installer labeled it as "ROOT" and mounted it as
f8143472 70
cfde13a4 71 ROOT 288G 12G 276G 4% /
f8143472 72
85e01a9d 73A PFS is a Pseudo File System inside a HAMMER file system. The HAMMER file system in which the PFSes are created is referred to as the root file system. You should not confuse the "root" file system with the Label "ROOT", the label can be anything. It is just that the installer labeled it as ROOT because it is mounted as `/`.
f8143472 74
85e01a9d 75Now inside the ROOT HAMMER file system you find the installed created 7 PFSes from the `df -h` output above, let us see how they are mounted in `/etc/fstab`:
f8143472 76
cfde13a4 77 # cat /etc/fstab
85e01a9d 78
cfde13a4 79 # Device Mountpoint FStype Options Dump Pass#
5ce2e546 80 /dev/serno/9VMBWDM1.s1a /boot ufs rw 1 1
81 /dev/serno/9VMBWDM1.s1b none swap sw 0 0
82 /dev/serno/9VMBWDM1.s1d / hammer rw 1 1
cfde13a4 83 /pfs/var /var null rw 0 0
84 /pfs/tmp /tmp null rw 0 0
85 /pfs/usr /usr null rw 0 0
86 /pfs/home /home null rw 0 0
87 /pfs/usr.obj /usr/obj null rw 0 0
88 /pfs/var.crash /var/crash null rw 0 0
89 /pfs/var.tmp /var/tmp null rw 0 0
90 proc /proc procfs rw 0 0
91
f8143472 92
a4b3282d 93The PFSes are mounted using a NULL mount because they are also HAMMER file systems. You can read more on NULL mounts here [mount_null(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=mount_null&section=8).
f8143472 94
85e01a9d 95You don't need to specify a size for the PFSes like you do for logical volumes inside a volume group for LVM. All the free space in the root HAMMER file system is available to all the PFSs. That is the reason in the `df -h` output above you saw free space is same for all PFSes and the root HAMMER file system.
f8143472 96
85e01a9d 97Now if you look in `/var`
f8143472 98
5ce2e546 99 # cd /var/
100 # ls
101 account backups caps cron empty log msgs run spool yp at
102 cache crash db games lib mail preserve rwho tmp
f8143472 103
104you will find the above directories.
105
85e01a9d 106If you look at the status of one of the PFSes, e.g. `/usr` you will see `/var/hammer` is the default snapshot directory.
f8143472 107
85e01a9d 108 # hammer pfs-status /usr/
5ce2e546 109 /usr/ PFS #3 {
110 sync-beg-tid=0x0000000000000001
111 sync-end-tid=0x0000000117ac6270
112 shared-uuid=f33e318e-d2af-11df-b588-01138fad54f5
113 unique-uuid=f33e31cb-d2af-11df-b588-01138fad54f5
114 label=""
115 prune-min=00:00:00
116 operating as a MASTER
117 snapshots directory defaults to /var/hammer/<pfs>
118 }
a4b3282d 119
85e01a9d 120There is no "hammer" directory in `/var` now. That is because no snapshots are yet taken. You can verify this by checking the snapshots available for `/usr`
f8143472 121
5ce2e546 122 # hammer snapls /usr
123 Snapshots on /usr PFS #3
124 Transaction ID Timestamp Note
f8143472 125
85e01a9d 126The best way to take a snapshot of all PFSes is to run the command `hammer cleanup`. It does a lot of things but the fist thing it does during cleanup of a PFS is to take its snapshots as configured.
f8143472 127
5ce2e546 128 # sudo hammer cleanup
129 cleanup / - HAMMER UPGRADE: Creating snapshots
130 Creating snapshots in /var/hammer/root
131 handle PFS #0 using /var/hammer/root
132 snapshots - run
133 prune - run
134 rebalance - run..
135 reblock - run....
136 recopy - run....
137 cleanup /var - HAMMER UPGRADE: Creating snapshots
85e01a9d 138 [...]
5ce2e546 139 cleanup /tmp - HAMMER UPGRADE: Creating snapshots
85e01a9d 140 [...]
5ce2e546 141 cleanup /usr - HAMMER UPGRADE: Creating snapshots
85e01a9d 142 [...]
5ce2e546 143 cleanup /home - HAMMER UPGRADE: Creating snapshots
85e01a9d 144 [...]
5ce2e546 145 cleanup /usr/obj - HAMMER UPGRADE: Creating snapshots
85e01a9d 146 [...]
5ce2e546 147 cleanup /var/crash - HAMMER UPGRADE: Creating snapshots
85e01a9d 148 [...]
5ce2e546 149 cleanup /var/tmp - HAMMER UPGRADE: Creating snapshots
85e01a9d 150 [...]
5ce2e546 151 cleanup /var/isos - HAMMER UPGRADE: Creating snapshots
85e01a9d 152 [...]
f8143472 153
85e01a9d 154No snapshots were taken for `/tmp`, `/usr/obj` and `/var/tmp`. This is because the PFSes are flagged as `nohistory`. HAMMER tracks history for all files in a PFS, naturally this consumes disk space until the history is pruned. To prevent that temporary files on the mentioned PFSes (e.g., object files, crash dumps) consume disk space, the PFSes are marked as `nohistory`.
f8143472 155
85e01a9d 156In `/var` will be a new directory called *hammer* with the following sub directories
f8143472 157
5ce2e546 158
159 # cd hammer/
160 # ls -l
161 total 0
162 drwxr-xr-x 1 root wheel 0 Oct 13 11:51 home
163 drwxr-xr-x 1 root wheel 0 Oct 13 11:42 root
164 drwxr-xr-x 1 root wheel 0 Oct 13 11:43 tmp
165 drwxr-xr-x 1 root wheel 0 Oct 13 11:51 usr
166 drwxr-xr-x 1 root wheel 0 Oct 13 11:54 var
167
f8143472 168
85e01a9d 169Well let us look inside `/var/hammer/usr`
f8143472 170
5ce2e546 171
172 # cd usr/
173 # ls -l
174 total 0
175 drwxr-xr-x 1 root wheel 0 Oct 13 11:54 obj
176 lrwxr-xr-x 1 root wheel 25 Oct 13 11:43 snap-20101013-1143 -> /usr/@@0x0000000117ac6cb0
177
f8143472 178
85e01a9d 179We have a symlink pointing to the snapshot transaction ID shown below.
f8143472 180
5ce2e546 181
182 # hammer snapls /usr
183 Snapshots on /usr PFS #3
184 Transaction ID Timestamp Note
185 0x0000000117ac6cb0 2010-10-13 11:43:04 IST -
186 #
187
f8143472 188
a4b3282d 189You can read more about snapshots, prune, reblance, reblock, recopy etc from [hammer(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=hammer&section=8) especially look under the heading "cleanup [filesystem ...]"
f8143472 190
191You can learn more about PFS mirroring [here](http://www.dragonflybsd.org/docs/how_to_implement_hammer_pseudo_file_system__40___pfs___41___slave_mirroring_from_pfs_master/)
192
f1895ba8 193In order to correctly map hard disk sernos to device names you can use the 'devattr' command.
930112c5 194
195 # udevd
196 # devattr -d "ad*" -p serno
197 Device ad4:
198 serno = Z2AD9WN4
199 Device ad4s1:
200 Device ad4s1d:
201
202 Device ad5:
203 serno = 9VMRFDSY
204 Device ad5s1:
205 Device ad5s1d:
206
207 Device ad3:
208 serno = Z2AD9WLW
209 Device ad3s1:
210 Device ad3s1a:
211 Device ad3s1b:
212 Device ad3s1d:
213
214Or if your disks are 'da', just change it as appropiate.
215
79923a10 216## Configuring and Starting the SSH Server
52923da9 217
85e01a9d 218Described in detail [[here|/docs/newhandbook/sshserver/]]
52923da9 219
79923a10 220## Software/Programs and Configuration Files Location
f8143472 221
85e01a9d 222DragonFly default installation contains the base software/programs from the DragonFly project itself and few other software from [pkgsrc](http://www.netbsd.org/docs/software/packages.html) which is the DragonFly official package management system. Ready to install binary software from pkgsrc is referred to as *packages*.
f8143472 223
224The base programs are located in the folders
5ce2e546 225
226 /bin /sbin
227 /usr/bin /usr/sbin
5ce2e546 228
85e01a9d 229The configuration files for the base system can be found in `/etc`. There is also `/usr/local/etc` which is used by third-party programs. The software/programs from pkgsrc are located in `/usr/pkg/bin` and `/usr/pkg/sbin`. Their configuration files are found in `/usr/pkg/etc`.
f8143472 230
85e01a9d 231## Installing Third-party Software
f8143472 232
85e01a9d 233Have a look at the [[pkgsrc howto|docs/howtos/HowToPkgsrc/]] for an in-depth description about dealing with third-party pkgsrc packages.
f8143472 234
85e01a9d 235### Using pkgin
d68c293b 236
85e01a9d 237For those who are new to the DragonFly way of doing things can also have the Debian's apt like way of installing, removing and updating packages. *pkgin* does things similar to *apt-get* or *aptitude* or *yum* for that matter.
f8143472 238
f9a32fca 239First we need to configure *pkgin* to use a repository which contains the pkgsrc binary packages. For this example we will use the main DragonFly server. **Note**: Be sure to use a local [[mirror|mirrors/]] for better performance and to reduce load on the main servers. From 3.0 onward this entry should already be there.
f8143472 240
f9a32fca 241 # echo "http://mirror-master.dragonflybsd.org/packages/$arch/DragonFly-$osrelease/stable/All/" > \
85e01a9d 242 /usr/pkg/etc/pkgin/repositories.conf
f8143472 243
5ce2e546 244
85e01a9d 245Now to update *pkgin* with the list of latest packages available from that repository.
f8143472 246
5ce2e546 247
248 # pkgin update
249 cleaning database from
929a51a8 250 http://mirror-master.dragonflybsd.org/packages/i386/DragonFly-2.8.2/stable/All/
5ce2e546 251 entries...
252 downloading pkg_summary.bz2: 100%
253 processing remote summary
929a51a8 254 (http://mirror-master.dragonflybsd.org/packages/i386/DragonFly-2.8.2/stable/All/)...
5ce2e546 255 updating database: 100%
f8143472 256
257Now to upgrade packages that are already installed in the system
258
5ce2e546 259
260 # pkgin full-upgrade
261 6 packages to be upgraded: freetype2-2.3.12 gtar-info-1.22
262 openldap-client-2.4.21 png-1.4.2 python26-2.6.5 tiff-3.9.4
263 1 packages to be removed: asciidoc-8.6.1
264 6 packages to be installed: png-1.4.3 python26-2.6.5nb1 tiff-3.9.4nb1
265 freetype2-2.4.2 gtar-info-1.23 openldap-client-2.4.23 (15M to
266 download, 59M to install)
267 proceed ? [y/N] y
268 downloading packages...
269 downloading png-1.4.3.tgz: 100%
270 downloading python26-2.6.5nb1.tgz: 100%
271 downloading tiff-3.9.4nb1.tgz: 100%
272 downloading freetype2-2.4.2.tgz: 100%
273 downloading gtar-info-1.23.tgz: 100%
274 downloading openldap-client-2.4.23.tgz: 100%
275 .....
276
85e01a9d 277In order to search for a new package, for example *rdesktop*.
5ce2e546 278
279
280 # pkgin search rdesktop
281 rdesktop-1.6.0 = Open-source Remote Desktop Protocol client
282 tsclient-0.132nb25 GNOME2 Frontend for rdesktop
283
284 =: package is installed and up-to-date
285 <: package is installed but newer version is available
286 >: installed package has a greater version than available package
287
f8143472 288To search for a package and install it you can do the following. If there are different versions of the package available in the repository it will show you the list and you need to specify one from them explicitly. At the end of the installation it will show you a message if you need any further configuration for the software to work in a particular way.
289
85e01a9d 290 # pkgin search mysql-client
5ce2e546 291 mysql-client-4.1.22nb4 MySQL 4, a free SQL database (client)
292 mysql-client-5.0.91 MySQL 5, a free SQL database (client)
293 mysql-client-5.1.49 MySQL 5, a free SQL database (client)
294
295 =: package is installed and up-to-date
296 <: package is installed but newer version is available
297 >: installed package has a greater version than available package
85e01a9d 298
299 # pkgin install mysql-client
5ce2e546 300 there's more than one version available for this package.
301 please re-run pkgin with a package name matching one of the following:
302 mysql-client-4.1.22nb4
303 mysql-client-5.0.91
304 mysql-client-5.1.49
305 nothing to do.
85e01a9d 306
307 # pkgin install mysql-client-5.1.49
5ce2e546 308 calculating dependencies for mysql-client-5.1.49...
309 nothing to upgrade.
310 1 packages to be installed: mysql-client-5.1.49 (7620K to download, 24M to install)
311 proceed ? [y/N] y
312 downloading packages...
313 downloading mysql-client-5.1.49.tgz: 100%
314 installing packages...
315 installing mysql-client-5.1.49...
85e01a9d 316 [...]
5ce2e546 317 processing local summary...
318 updating database: 100%
319 marking mysql-client-5.1.49 as non auto-removable
320
f8143472 321To remove a package
322
5ce2e546 323 # pkgin remove mysql-client
324 1 packages to delete: mysql-client-5.1.49
325 proceed ? [y/N] y
326 removing mysql-client-5.1.49...
327 processing local summary...
328 updating database: 100%
329
330
85e01a9d 331*pkgin* is very similar to *apt-get, aptitude , yum, emerge, pacman* and friends in the Linux world.
f8143472 332
85e01a9d 333All the *pkgin* commands can be seen [here](http://imil.net/pkgin/). *pkgin* comes installed with the default DragonFly install so you can skip the installation part on that page.
f8143472 334
335To install a desktop you can [read the following](http://www.dragonflybsd.org/docs/newhandbook/X/)
85e01a9d 336Other Docs can be found [here](http://www.dragonflybsd.org/docs/newhandbook/X/).