Improve markup a bit; also disklabel64 (default used) c part. isn't whole disk, delet...
[ikiwiki.git] / docs / newhandbook / environmentquickstart / index.mdwn
1 This document describes the DragonFly environment one will find on a newly installed system using the default options in the installer after selecting HAMMER for the file systems option.
2
3 [[!toc levels=3 ]]
4
5 ## Disk, Partition layout, Mount points, PFSes, Snapshots
6
7 If you followed the default options during installation you will be
8 left with a system with the following disk configuration
9
10
11     # df -h
12     Filesystem                Size   Used  Avail Capacity  Mounted on
13     ROOT                      288G    12G   276G     4%    /
14     devfs                     1.0K   1.0K     0B   100%    /dev
15     /dev/serno/9VMBWDM1.s1a   756M   138M   558M    20%    /boot
16     /pfs/@@-1:00001           288G    12G   276G     4%    /var
17     /pfs/@@-1:00002           288G    12G   276G     4%    /tmp
18     /pfs/@@-1:00003           288G    12G   276G     4%    /usr
19     /pfs/@@-1:00004           288G    12G   276G     4%    /home
20     /pfs/@@-1:00005           288G    12G   276G     4%    /usr/obj
21     /pfs/@@-1:00006           288G    12G   276G     4%    /var/crash
22     /pfs/@@-1:00007           288G    12G   276G     4%    /var/tmp
23     procfs                    4.0K   4.0K     0B   100%    /proc
24
25 In this example
26
27 **/dev/serno/9VMBWDM1** is the hard disk specified with serial number,
28
29 **/dev/serno/9VMBWDM1.s1** is the first slice on the hard disk.
30
31 Let us see its disklabel
32
33
34     # sudo disklabel /dev/serno/9VMBWDM1.s1
35     # /dev/serno/9VMBWDM1.s1:
36     #
37     # Informational fields calculated from the above
38     # All byte equivalent offsets must be aligned
39     #
40     # boot space:    1044992 bytes
41     # data space:  312567643 blocks # 305241.84 MB (320069266944 bytes)
42     #
43     # NOTE: If the partition data base looks odd it may be
44     #       physically aligned instead of slice-aligned
45     #
46     diskid: e67030af-d2af-11df-b588-01138fad54f5
47     label:
48     boot2 data base:      0x000000001000
49     partitions data base: 0x000000100200
50     partitions data stop: 0x004a85ad7000
51     backup label:         0x004a85ad7000
52     total size:           0x004a85ad8200    # 305242.84 MB
53     alignment: 4096
54     display block size: 1024        # for partition display only
55
56     16 partitions:
57     #          size     offset    fstype   fsuuid
58       a:     786432          0    4.2BSD    #     768.000MB
59       b:    8388608     786432      swap    #    8192.000MB
60       d:  303392600    9175040    HAMMER    #  296281.836MB
61       a-stor_uuid: eb1c8aac-d2af-11df-b588-01138fad54f5
62       b-stor_uuid: eb1c8aec-d2af-11df-b588-01138fad54f5
63       d-stor_uuid: eb1c8b21-d2af-11df-b588-01138fad54f5
64
65
66 The slice has 3 partitions:
67
68 a - for /boot
69
70 b - for swap
71
72 d - for /, a HAMMER file system labeled ROOT
73
74 When you create a HAMMER file system you must give it a label, here the Installer labeled it as "ROOT" and mounted it as
75
76     ROOT                      288G    12G   276G     4%    /
77
78 Now a 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
79 because it is mounted as /)
80
81 Now 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 fstab
82
83     # cat /etc/fstab
84     # Device                Mountpoint      FStype  Options         Dump    Pass#
85     /dev/serno/9VMBWDM1.s1a         /boot           ufs     rw      1       1
86     /dev/serno/9VMBWDM1.s1b         none            swap    sw      0       0
87     /dev/serno/9VMBWDM1.s1d         /               hammer  rw      1       1
88     /pfs/var                /var            null    rw              0       0
89     /pfs/tmp                /tmp            null    rw              0       0
90     /pfs/usr                /usr            null    rw              0       0
91     /pfs/home               /home           null    rw              0       0
92     /pfs/usr.obj    /usr/obj                null    rw              0       0
93     /pfs/var.crash  /var/crash              null    rw              0       0
94     /pfs/var.tmp    /var/tmp                null    rw              0       0
95     proc                    /proc           procfs  rw              0       0
96
97
98 The 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).
99
100 You 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 for all the PFSes to grow. 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.
101
102 Now if you look in /var
103
104     # cd /var/
105     # ls
106     account   backups   caps   cron    empty   log   msgs   run   spool   yp  at        
107     cache     crash     db     games   lib     mail  preserve   rwho  tmp
108
109 you will find the above directories.
110
111 If you look at the status of one of the PFSes say /usr you will see /var/hammer is the default snapshot directory.
112
113
114    # hammer pfs-status /usr/
115     /usr/   PFS #3 {
116         sync-beg-tid=0x0000000000000001
117         sync-end-tid=0x0000000117ac6270
118         shared-uuid=f33e318e-d2af-11df-b588-01138fad54f5
119         unique-uuid=f33e31cb-d2af-11df-b588-01138fad54f5
120         label=""
121         prune-min=00:00:00
122         operating as a MASTER
123         snapshots directory defaults to /var/hammer/<pfs>
124     }
125    #
126
127
128 But there 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
129
130     # hammer snapls /usr
131     Snapshots on /usr       PFS #3
132     Transaction ID          Timestamp               Note
133     #
134
135 The best way to take a snapshot of the whole system 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.
136
137     # sudo hammer cleanup
138     cleanup /                    - HAMMER UPGRADE: Creating snapshots
139             Creating snapshots in /var/hammer/root
140      handle PFS #0 using /var/hammer/root
141                snapshots - run
142                    prune - run
143                rebalance - run..
144                  reblock - run....
145                   recopy - run....
146     cleanup /var                 - HAMMER UPGRADE: Creating snapshots
147             Creating snapshots in /var/hammer/var
148      handle PFS #1 using /var/hammer/var
149                snapshots - run
150                    prune - run
151                rebalance - run..
152                  reblock - run....
153                   recopy - run....
154     cleanup /tmp                 - HAMMER UPGRADE: Creating snapshots
155             Creating snapshots in /var/hammer/tmp
156      handle PFS #2 using /var/hammer/tmp
157                snapshots - disabled
158                    prune - run
159                rebalance - run..
160                  reblock - run....
161                   recopy - run....
162     cleanup /usr                 - HAMMER UPGRADE: Creating snapshots
163             Creating snapshots in /var/hammer/usr
164      handle PFS #3 using /var/hammer/usr
165                snapshots - run
166                    prune - run
167                rebalance - run..
168                  reblock - run....
169                   recopy - run....
170     cleanup /home                - HAMMER UPGRADE: Creating snapshots
171             Creating snapshots in /var/hammer/home
172      handle PFS #4 using /var/hammer/home
173                snapshots - run
174                    prune - run
175                rebalance - run..
176                  reblock - run....
177                   recopy - run....
178     cleanup /usr/obj             - HAMMER UPGRADE: Creating snapshots
179             Creating snapshots in /var/hammer/usr/obj
180      handle PFS #5 using /var/hammer/usr/obj
181                snapshots - disabled
182                    prune - run
183                rebalance - run..
184                  reblock - run....
185                   recopy - run....
186     cleanup /var/crash           - HAMMER UPGRADE: Creating snapshots
187             Creating snapshots in /var/hammer/var/crash
188      handle PFS #6 using /var/hammer/var/crash
189                snapshots - run
190                    prune - run
191                rebalance - run..
192                  reblock - run....
193                   recopy - run....
194     cleanup /var/tmp             - HAMMER UPGRADE: Creating snapshots
195             Creating snapshots in /var/hammer/var/tmp
196      handle PFS #7 using /var/hammer/var/tmp
197                snapshots - disabled
198                    prune - run
199                rebalance - run..
200                  reblock - run....
201                   recopy - run....
202     cleanup /var/isos            - HAMMER UPGRADE: Creating snapshots
203             Creating snapshots in /var/hammer/var/isos
204      handle PFS #8 using /var/hammer/var/isos
205                snapshots - run
206                    prune - run
207                rebalance - run..
208                  reblock - run....
209                   recopy - run....
210     #
211
212 You  must have noticed that snapshots were not taken for '/tmp', '/usr/obj' and '/var/tmp'. That is how it is automatically configured by the installer.
213
214 Let us look again in /var now
215
216     # ls
217     account   backups   caps   cron    empty   hammer log   msgs   run   spool   yp  
218     at        cache     crash     db     games   lib     mail  preserve   rwho  tmp
219
220
221 We have a new directory called "hammer" with the following sub directories
222
223
224     # cd hammer/
225     # ls -l
226     total 0
227     drwxr-xr-x  1 root  wheel  0 Oct 13 11:51 home
228     drwxr-xr-x  1 root  wheel  0 Oct 13 11:42 root
229     drwxr-xr-x  1 root  wheel  0 Oct 13 11:43 tmp
230     drwxr-xr-x  1 root  wheel  0 Oct 13 11:51 usr
231     drwxr-xr-x  1 root  wheel  0 Oct 13 11:54 var
232
233
234 Well let us look inside /var/hammer/usr 
235
236
237     # cd usr/
238     # ls -l
239     total 0
240     drwxr-xr-x  1 root  wheel   0 Oct 13 11:54 obj
241     lrwxr-xr-x  1 root  wheel  25 Oct 13 11:43 snap-20101013-1143 -> /usr/@@0x0000000117ac6cb0
242
243
244 We have a symlink pointing to the snapshot Transaction ID shown below.
245
246
247
248     # hammer snapls /usr
249     Snapshots on /usr       PFS #3
250     Transaction ID          Timestamp               Note
251     0x0000000117ac6cb0      2010-10-13 11:43:04 IST -
252     #
253
254
255 You 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 ...]"
256
257 You 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/)
258
259 ## Configuring and Starting the SSH Server
260
261 Described in detail [here](http://www.dragonflybsd.org/docs/docs/newhandbook/sshserver/)
262
263 ## Software/Programs and Configuration Files Location 
264
265 DragonFly 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 "<b>Packages</b>".
266
267 The base programs are located in the folders 
268
269     /bin    /sbin
270     /usr/bin   /usr/sbin
271     /usr/local/bin   /usr/local/sbin
272
273 Their configuration files are found mainly in <b>/etc</b>. there is also <b> /usr/local/etc </b>
274
275 The software/programs from pkgsrc are located in <b>/usr/pkg/bin and /usr/pkg/sbin</b>. Their configuration files are found in <b>/usr/pkg/etc</b>.
276
277 ## Installing new Software from pkgsrc packages 
278
279 A Detailed description on how to use packages and pkgsrc are given [[here|docs/howtos/HowToPkgsrc]].
280
281 For those who are new to the BSD way of doing things can also have the Debian's apt like way of installing, removing and updating packages. 
282
283 **pkgin** does things similar to **apt-get** or **aptitude** or **yum** for that matter.
284
285 First we need to configure pkgin to use a repository which contains the pkgsrc binary packages. You can get a list of DragonFly mirrors [here](http://www.dragonflybsd.org/mirrors/). For this example we will use the <b>Belarus</b> [HTTP mirror](http://mirror.datacenter.by/pub/DragonFlyBSD/) shown on that page first under Europe.
286
287
288     #echo "http://mirror.datacenter.by/pub/DragonFlyBSD/packages/i386/DragonFly-2.7/stable/All/" > /usr/pkg/etc/pkgin/repositories.conf
289
290
291 Now to update pkgin with the list of latest packages available from that repository.
292
293
294     # pkgin update
295     cleaning database from
296     http://mirror.datacenter.by/pub/DragonFlyBSD/packages/i386/DragonFly-2.7/stable/
297     entries...
298     downloading pkg_summary.bz2: 100%
299     processing remote summary
300     (http://mirror.datacenter.by/pub/DragonFlyBSD/packages/i386/DragonFly-2.7/stable/All)...
301     updating database: 100%
302
303 Now to upgrade packages that are already installed in the system
304
305
306     # pkgin full-upgrade
307     6 packages to be upgraded: freetype2-2.3.12 gtar-info-1.22
308     openldap-client-2.4.21 png-1.4.2 python26-2.6.5 tiff-3.9.4
309     1 packages to be removed: asciidoc-8.6.1
310     6 packages to be installed: png-1.4.3 python26-2.6.5nb1 tiff-3.9.4nb1
311     freetype2-2.4.2 gtar-info-1.23 openldap-client-2.4.23 (15M to
312     download, 59M to install)
313     proceed ? [y/N] y
314     downloading packages...
315     downloading png-1.4.3.tgz: 100%
316     downloading python26-2.6.5nb1.tgz: 100%
317     downloading tiff-3.9.4nb1.tgz: 100%
318     downloading freetype2-2.4.2.tgz: 100%
319     downloading gtar-info-1.23.tgz: 100%
320     downloading openldap-client-2.4.23.tgz: 100%
321     .....
322
323 In order to search for a new Package for example **rdesktop**.
324
325
326     # pkgin search rdesktop
327     rdesktop-1.6.0 =     Open-source Remote Desktop Protocol client
328     tsclient-0.132nb25   GNOME2 Frontend for rdesktop
329     
330     =: package is installed and up-to-date
331     <: package is installed but newer version is available
332     >: installed package has a greater version than available package
333
334
335 If there are symbols **=** or **<** or **>** after a package name in the output then the last 3 lines of the output will explain them.
336
337 To 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.
338
339
340     dfly-vmsrv# pkgin search mysql-client
341     mysql-client-4.1.22nb4  MySQL 4, a free SQL database (client)
342     mysql-client-5.0.91  MySQL 5, a free SQL database (client)
343     mysql-client-5.1.49  MySQL 5, a free SQL database (client)
344     
345     =: package is installed and up-to-date
346     <: package is installed but newer version is available
347     >: installed package has a greater version than available package
348     dfly-vmsrv# pkgin install mysql-client
349     there's more than one version available for this package.
350     please re-run pkgin with a package name matching one of the following:
351     mysql-client-4.1.22nb4
352     mysql-client-5.0.91
353     mysql-client-5.1.49
354     nothing to do.
355     dfly-vmsrv# pkgin install mysql-client-5.1.49
356     calculating dependencies for mysql-client-5.1.49...
357     nothing to upgrade. 
358     1 packages to be installed: mysql-client-5.1.49 (7620K to download, 24M to install)
359     proceed ? [y/N] y
360     downloading packages...
361     downloading mysql-client-5.1.49.tgz: 100%
362     installing packages...
363     installing mysql-client-5.1.49...
364     ===========================================================================
365     $NetBSD: MESSAGE,v 1.1.1.1 2010/03/04 16:27:18 taca Exp $
366
367     To use the ``mysqlhotcopy'' script, you'll have to install the following
368     packages:
369
370             databases/p5-DBD-mysql
371             devel/p5-File-Temp
372
373     ===========================================================================
374     processing local summary...
375     updating database: 100%
376     marking mysql-client-5.1.49 as non auto-removable
377
378
379 To remove a package
380
381
382     # pkgin remove mysql-client
383     1 packages to delete: mysql-client-5.1.49
384     proceed ? [y/N] y
385     removing mysql-client-5.1.49...
386     processing local summary...
387     updating database: 100%
388
389
390 **pkgin** is very similar to **apt-get, aptitude , yum, emerge, pacman** and friends in the linux world.
391
392 All 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
393
394 To install a desktop you can [read the following](http://www.dragonflybsd.org/docs/newhandbook/X/)
395 Other Docs can be found [here](http://www.dragonflybsd.org/docs/newhandbook/X/). When ever you find **pkg_add** or **pkg_radd** used to install a software just use **pkgin** instead.