UPDATING

   1 # Updating Information for DragonFly users.
   2 #
   3 #
   4 # This file should warn you of any pitfalls which you might need to work around
   5 # when trying to update your DragonFly system.  The information below is
   6 # in reverse-time order, with the latest information at the top.
   7 #
   8 # If you discover any problem, please contact the bugs@lists.dragonflybsd.org
   9 # mailing list with the details.
  10 #
  11 # $DragonFly: src/UPDATING,v 1.26 2008/09/15 20:03:36 thomas Exp $
  12
  13 +-----------------------------------------------------------------------+
  14 +         20100924
  15 +         UPGRADING DRAGONFLY FROM 2.6 to 2.8 or HEAD
  16 +-----------------------------------------------------------------------+
  17
  18 Loader
  19 =======
  20
  21 A new loader (dloader) has been added which better handles booting from
  22 multiple kernel/module versions.
  23
  24 To upgrade (Only for this upgrade, for post 2.8 upgrades see GENERAL below)
  25
  26         cd /usr/src
  27         make buildworld
  28         make installworld
  29         make upgrade
  30         make buildkernel KERNCONF=<KERNELNAME>
  31         make installkernel KERNCONF=<KERNELNAME>
  32
  33 Note that you must installworld and run the 'upgrade' target before
  34 installing the new kernel.
  35
  36 BIND
  37 =====
  38
  39 BIND has been removed from the base system.  The ldns and drill tools have
  40 been added for basic functionality.  Use 'drill' where you would normally
  41 use nslookup or dig, or install BIND from pkgsrc.  It's available as
  42 net/bind95, net/bind96, or net/bind97 as of this writing.
  43
  44 This only affects older systems upgrading to 2.8.  New 2.8+ installs
  45 include BIND as a pkgsrc package.
  46
  47 +-----------------------------------------------------------------------+
  48 +         UPGRADING DRAGONFLY ON AN EXISTING DRAGONFLY SYSTEM           +
  49 +                               GENERAL                                 +
  50 +-----------------------------------------------------------------------+
  51
  52 Instructions on how to obtain and maintain DragonFly source code using git
  53 are in the development(7) manual page.
  54
  55 To upgrade a DragonFly system from sources you run the following sequence:
  56
  57         cd /usr/src
  58         make buildworld
  59         make buildkernel KERNCONF=<KERNELNAME>
  60         make installkernel KERNCONF=<KERNELNAME>
  61         make installworld
  62
  63 You will also want to run the 'upgrade' target to upgrade your /etc and the
  64 rest of your system.  The upgrade target is aware of stale files created by
  65 older DragonFly installations and should delete them automatically.
  66
  67         make upgrade
  68
  69 See the build(7) manual page for further information.
  70
  71 Once you've done a full build of the world and kernel you can do incremental
  72 upgrades of either by using the 'quickworld' and 'quickkernel' targets
  73 instead of 'buildworld' and 'buildkernel'.  If you have any problems with
  74 the quick targets, try updating your repo first, and then a full buildworld
  75 and buildkernel as shown above, before asking for help.
  76
  77 +-----------------------------------------------------------------------+
  78 +         UPGRADING FROM DRAGONFLY <= 2.0 TO DRAGONFLY >= 2.1           +
  79 +-----------------------------------------------------------------------+
  80
  81 In 2.1 kernel and modules has moved to boot directory.  For most cases
  82 this is handled automatically by 'make upgrade'.  A few cases needs manual
  83 intervention:
  84
  85  * When installing a kernel without first doing a make buildworld,
  86    installworld and upgrade to the same DESTDIR as kernel:
  87    make DESTDIR/boot directory and move kernel and modules into this boot
  88    directory; also move kernel.old and modules.old.
  89    Typical example is vkernel(7), use (no modules used):
  90
  91         cd /var/vkernel
  92         mkdir boot
  93         chflags noschg kernel
  94         mv kernel kernel.old boot
  95         chflags schg boot/kernel
  96
  97  * When using a boot-only partition, /boot/loader.rc needs to be edited:
  98    delete occurrences of '/boot/'.
  99    These occurences can normally be deleted in any case, see loader(8).
 100
 101 +-----------------------------------------------------------------------+
 102 +         UPGRADING FROM DRAGONFLY <= 1.8 TO DRAGONFLY >= 1.9           +
 103 +-----------------------------------------------------------------------+
 104
 105 In 1.9 major changes to the disk management infrastructure have taken
 106 place.  make upgrade may not catch all of your disk devices in /dev,
 107 so after upgrading be sure to cd /dev; ./MAKEDEV <blah> where <blah>
 108 are all of your disk devices.  HOWEVER, from late 2.3 on we run devfs
 109 and MAKEDEV no longer exists.
 110
 111 The biggest changes in 1.9 are:
 112
 113 (1) That whole-slice devices such as da0s1 no longer share the same device
 114     id as partition c devices such as da0s1c.
 115
 116 (2) The whole-disk device (e.g. da0) is full raw access to the disk,
 117     with no snooping or reserved sectors.  Consequently you cannot run
 118     disklabel on this device.  Instead you must run disklabel on a
 119     whole-slice device.
 120
 121 (3) The 'compatibility' partitions now use slice 0 in the device name,
 122     so instead of da0a you must specify da0s0a.  Also, as per (1) above,
 123     accessing the disklabel for the compatibility partitions must be
 124     done via slice 0 (da0s0).
 125
 126 (4) Many device drivers that used to fake up labels, such as CD, ACD, VN,
 127     and CCD now run through the disk management layer and are assigned
 128     real disk management devices.   VN and CCD in particular do not usually
 129     use a MBR and disklabels must be accessed through the compatibility
 130     slice 0.  Your /etc/ccd.conf file still specifies 'ccd0', though, you
 131     don't name it 'ccd0s0' in the config file.
 132
 133 Generally speaking, you have to get used to running fdisk and disklabel on
 134 the correctly specified device names.  A lot of the wiggle, such as running
 135 disklabel on a partition, has been removed.
 136
 137 +-----------------------------------------------------------------------+
 138 +         UPGRADING FROM OLDER VERSIONS OF DRAGONFLY OR FREEBSD         +
 139 +-----------------------------------------------------------------------+
 140
 141 > Kerberos IV
 142 -------------
 143
 144 Kerberos IV (eBones) was removed from the tree, please consider moving to
 145 Kerberos 5 (Heimdal).
 146
 147 > Package Management System
 148 ---------------------------
 149
 150 Starting with the 1.4 release, DragonFly uses NetBSD's pkgsrc package
 151 management system.  The necessary tools to build and maintain packages
 152 are provided in /usr/pkg/bin and /usr/pkg/sbin.  Make sure that these
 153 directories are in your PATH variable.
 154
 155 In order to obtain a reasonably current snapshot of the pkgsrc tree, use
 156 the tarball from NetBSD:
 157
 158         fetch -o /tmp/pkgsrc.tar.gz ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc.tar.gz
 159         cd /usr; tar -xzf /tmp/pkgsrc.tar.gz; chown -R root:wheel pkgsrc
 160
 161 This tree can then be kept up to date with cvs update:
 162
 163         cd /usr/pkgsrc; cvs up
 164
 165 NOTE! If you upgraded from a pre-1.4 system to 1.4 or later, you need to
 166 build and install the pkgsrc bootstrap manually:
 167
 168         cd /usr/pkgsrc/bootstrap
 169         ./bootstrap --pkgdbdir /var/db/pkg --prefix /usr/pkg
 170
 171 +-----------------------------------------------------------------------+
 172 +         UPGRADING DRAGONFLY ON AN EXISTING DRAGONFLY SYSTEM           +
 173 +         UPDATING FROM PRE-1.2 SYSTEMS OR FreeBSD 4.x TO               +
 174 +         DRAGONFLY 1.3+ (EITHER PREVIEW or HEAD)                       +
 175 +-----------------------------------------------------------------------+
 176
 177 The compatibility shims for the build environment have been removed, you
 178 have to update to DragonFly 1.2 release branch first.
 179
 180 The default PAM configuration has moved from /etc/pam.conf to /etc/pam.d/.
 181 The existing configuration can be converted using /etc/pam.d/convert.sh.
 182 Entries in /etc/pam.d/ override entries in /etc/pam.conf. In addition
 183 the pam_skey.so module was retired, you have to remove it manually from
 184 your configuration, when you convert it.
 185
 186 > Required user and group IDs when upgrading from either FreeBSD or DragonFly
 187 ---------------------
 188
 189 The following users may be missing from your password file.  Use vipw and
 190 add any that are missing:
 191
 192 smmsp:*:25:25::0:0:Sendmail Submission User:/var/spool/clientmqueue:/sbin/nologin
 193 _pflogd:*:64:64::0:0:pflogd privsep user:/var/empty:/sbin/nologin
 194
 195 The following groups may be missing from your group file.  Use vi /etc/group
 196 and add any that are missing:
 197
 198 smmsp:*:25:
 199 authpf:*:63:
 200 _pflogd:*:64:
 201
 202
 203 > Upgrading to DragonFly from FreeBSD
 204 ---------------------
 205
 206 You can build the DragonFly world and DragonFly kernels on a FreeBSD-4.x or
 207 FreeBSD-5.x machine and then install DragonFly over FreeBSD, replacing
 208 FreeBSD.  Note that the DragonFly buildworld target does not try to reuse
 209 make depend information, it starts from scratch, so no pre-cleaning of the
 210 object hierarchy is necessary.
 211
 212         # get the CVS repository (it is placed in /home/dcvs, 500MB).
 213         # Please use the -h option and a mirror site to pull the
 214         # initial repository, but feel free to use the main repository
 215         # machine to pull updates.
 216         cvsup /usr/share/examples/cvsup/DragonFly-cvs-supfile
 217         # install the source from the CVS hierarchy (remove preexisting
 218         # FreeBSD src first) (500MB)
 219         cd /usr
 220         rm -rf src
 221         cvs -R -d /home/dcvs checkout -P src
 222
 223         # build it (500MB used in /usr/obj)
 224         #
 225         cd /usr/src
 226         make buildworld
 227         make buildkernel KERNCONF=<KERNELNAME>
 228
 229 Once you have built DragonFly you have to install it over FreeBSD.  Since
 230 DragonFly does not track changes made by FreeBSD to its include file
 231 hierarchy and include file pollution can cause all sorts of unexpected
 232 compilation issues to come up, it is best to wipe your include hierarchy
 233 prior to installing DragonFly.  Note that you should not wipe any installed
 234 FreeBSD header files or binaries until after you have successfully completed
 235 the build steps above.
 236
 237         rm -rf /usr/include
 238         mkdir /usr/include
 239         make installkernel KERNCONF=<KERNELNAME>
 240         make installworld
 241
 242 Then you need to upgrade your system.  DragonFly's 'make upgrade' target
 243 will unconditionally upgrade the /etc files that sysops do not usually
 244 mess around with, such as the files in /etc/rc.d.  It will also remove any
 245 obsolete files such as utilities and manpages that have been removed from
 246 the system since the version you're coming from.  If you are unsure we
 247 recommend that you make a backup of at least your /etc before applying
 248 this step.  Note that DragonFly's RC system is basically RCNG from
 249 FreeBSD-5, but there are some differences in the contents of the RC files.
 250
 251         make upgrade
 252
 253 NOTE! Never do a 'make upgrade' before 'make installworld' has been run.
 254 Doing so might leave your system in an unusable state.
 255
 256 Finally we recommend that you do an 'ls -lta BLAH' for /bin, /sbin, /usr/bin,
 257 /usr/bin, and /usr/lib, and remove any stale files that you find.  Please
 258 report these files to the DragonFly developers so that they can be added to
 259 the 'upgrade' target.
 260