Annotation of src/UPDATING, revision 1.16.2.1

1.2       asmodai     1: $DragonFly$
1.1       dillon      2: 
1.2       asmodai     3: Updating Information for DragonFly users.
1.1       dillon      4: 
1.2       asmodai     5: This file should warn you of any pitfalls which you might need to work around
                      6: when trying to update your DragonFly system.
1.1       dillon      7: 
1.2       asmodai     8: If you discover any problem, please contact the bugs@lists.dragonflybsd.org
                      9: mailing list with the details.
1.1       dillon     10: 
1.2       asmodai    11: ------------------------------------------------------------------------------
1.1       dillon     12: 
1.16.2.1! justin     13: > Upgrading DragonFly from 1.2 to 1.4.
        !            14: ---------------------
        !            15: 
        !            16: There are 3 extra steps necessary to upgrade from 1.2 to 1.4.
        !            17: 
        !            18: - If you have a customized kernel configuration file, it will need
        !            19: this line:
        !            20: 
        !            21: options         COMPAT_DF12
        !            22: 
        !            23: - The default PAM configuration has moved from /etc/pam.conf to /etc/pam.d/.
        !            24: Conversion of the existing configuration is performed by commenting out
        !            25: any line in /etc/pam.conf that contains "pam_skey.so" and then
        !            26: running /etc/pam.d/convert.sh.
        !            27: 
        !            28: - You must reboot the system between the 'make installkernel' and 'make
        !            29: installworld' steps of the upgrade; the system needs to have a newer
        !            30: kernel running before the new world is installed.
        !            31: 
        !            32: ------------------------------------------------------------------------------
        !            33: 
        !            34: 
1.14      joerg      35: > Updating from pre-1.2 systems or FreeBSD 4.x to DragonFly 1.3+ (either
                     36:   PREVIEW or HEAD)
                     37: ---------------------
                     38: 
                     39: The compatiblity shims for the build environment have been removed, you
                     40: have to update to DragonFly 1.2 release branch first.
                     41: 
1.15      joerg      42: The default PAM configuration has moved from /etc/pam.conf to /etc/pam.d/.
                     43: The existing configuration can be converted using /etc/pam.d/convert.sh.
                     44: Entries in /etc/pam.d/ override entries in /etc/pam.conf. In addition
                     45: the pam_skey.so module was retired, you have to remove it manually from
                     46: your configuration, when you convert it.
1.14      joerg      47: 
1.8       dillon     48: > Required user and group IDs when upgrading from either FreeBSD or DragonFly
                     49: ---------------------
                     50: 
                     51: The following users may be missing from your password file.  Use vipw and
                     52: add any that are missing:
                     53: 
                     54: smmsp:*:25:25::0:0:Sendmail Submission User:/var/spool/clientmqueue:/sbin/nologin
1.9       joerg      55: _pflogd:*:64:64::0:0:pflogd privsep user:/var/empty:/sbin/nologin
                     56: _ntp:*:65:65::0:0:ntpd privsep user:/var/empty:/sbin/nologin
1.8       dillon     57: 
                     58: The following groups may be missing from your group file.  Use vi /etc/group
                     59: and add any that are missing:
                     60: 
                     61: smmsp:*:25:
                     62: authpf:*:63:
1.9       joerg      63: _pflogd:*:64:
                     64: _ntp:*:65:
1.8       dillon     65: 
                     66: 
1.7       dillon     67: > Upgrading to DragonFly from FreeBSD
1.2       asmodai    68: ---------------------
1.1       dillon     69: 
1.7       dillon     70: You can build the DragonFly world and DragonFly kernels on a FreeBSD-4.x or
                     71: FreeBSD-5.x machine and then install DragonFly over FreeBSD, replacing
                     72: FreeBSD.  Note that the DragonFly buildworld target does not try to reuse
                     73: make depend information, it starts from scratch, so no pre-cleaning of the
                     74: object hierarchy is necessary.
                     75: 
1.10      hmp        76:        # get the CVS repository (it is placed in /home/dcvs, 500MB).
1.7       dillon     77:        # Please use the -h option and a mirror site to pull the 
                     78:        # initial repository, but feel free to use the main repository
                     79:        # machine to pull updates.
1.12      swildner   80:        cvsup /usr/share/examples/cvsup/DragonFly-cvs-supfile
1.7       dillon     81:        # install the source from the CVS hierarchy (remove preexisting
                     82:        # FreeBSD src first) (500MB)
                     83:        cd /usr
                     84:        rm -rf src
                     85:        cvs -R -d /home/dcvs checkout src
                     86:        cvs -R -d /home/dcvs checkout dfports
1.1       dillon     87: 
1.7       dillon     88:        # build it (500MB used in /usr/obj)
                     89:        #
                     90:        cd /usr/src
                     91:        make buildworld
                     92:        make buildkernel KERNCONF=<KERNELNAME>
                     93: 
                     94: Once you have built DragonFly you have to install it over FreeBSD.  Since
                     95: DragonFly does not track changes made by FreeBSD to its include file 
                     96: hierarchy and include file pollution can cause all sorts of unexpected
                     97: compilation issues to come up, it is best to wipe your include hierarchy
                     98: prior to installing DragonFly.  Note that you should not wipe any installed
                     99: FreeBSD header files or binaries until after you have successfully completed
                    100: the build steps above.
1.6       dillon    101: 
1.7       dillon    102:        rm -rf /usr/include
1.6       dillon    103:        mkdir /usr/include
1.7       dillon    104:        make installkernel KERNCONF=<KERNELNAME>
                    105:        make installworld
                    106: 
1.16      swildner  107: Then you need to upgrade your system.  DragonFly's 'make upgrade' target 
1.7       dillon    108: will unconditionally upgrade the /etc files that sysops do not usually
1.16      swildner  109: mess around with, such as the files in /etc/rc.d.  It will also remove any
                    110: obsolete files such as utilities and manpages that have been removed from
                    111: the system since the version you're coming from.  If you are unsure we 
                    112: recommend that you make a backup of at least your /etc before applying
                    113: this step.  Note that DragonFly's RC system is basically RCNG from
                    114: FreeBSD-5, but there are some differences in the contents of the RC files.
1.7       dillon    115: 
                    116:        make upgrade
                    117: 
1.16      swildner  118: NOTE! Never do a 'make upgrade' before 'make installworld' has been run.
                    119: Doing so might leave your system in an unusable state.
                    120: 
1.7       dillon    121: Finally we recommend that you do an 'ls -lta BLAH' for /bin, /sbin, /usr/bin,
1.16      swildner  122: /usr/bin, and /usr/lib, and remove any stale files that you find.  Please
                    123: report these files to the DragonFly developers so that they can be added to
                    124: the 'upgrade' target.
1.7       dillon    125: 
                    126: ------------------------------------------------------------------------------
                    127: 
                    128: > Upgrading DragonFly on an existing DragonFly system.
                    129: ---------------------
                    130: 
                    131: The best way to upgrade DragonFly is to maintain a copy of the DragonFly
                    132: CVS repository via cvsup and to checkout the source base and DragonFly
                    133: ports via this repository.   The repository is stored in /home/dcvs by
                    134: default and requires about 500MB of disk space.  The checked out source
                    135: tree (/usr/src) requires about 500MB of disk space, and the build will
                    136: eat around 500MB of space out of /usr/obj.  To maintain the build you 
                    137: should reserve at least 2GB of disk space, and 3GB if you have the space.
                    138: 
                    139: Note: most people run cvsup via a root cron job to keep the repository up to
                    140: date.  Please limit such automatic updates to once a day and try to randomize
                    141: the hour and minute in the cron job a bit to avoid pileups.
                    142: 
1.10      hmp       143:        # get the CVS repository (it is placed in /home/dcvs)
1.12      swildner  144:        cvsup /usr/share/examples/cvsup/DragonFly-cvs-supfile
1.7       dillon    145:        # install the source from the CVS hierarchy
                    146:        cd /usr
1.11      joerg     147:        cvs -R -d /home/dcvs checkout -P src
                    148:        cvs -R -d /home/dcvs checkout -P dfports
1.7       dillon    149: 
                    150: Once you have the repository and broken out sources you can decide whether to
                    151: update your sources from the repository automatically or manually.  Since
                    152: you are tracking changes made to DragonFly, it is usually a good idea to
                    153: update the sources manually:
                    154: 
1.6       dillon    155:        cd /usr/src
1.11      joerg     156:        cvs update -dP
1.6       dillon    157: 
1.7       dillon    158: To upgrade a DragonFly system from sources you run the following sequence:
1.6       dillon    159: 
                    160:        cd /usr/src
1.7       dillon    161:        make buildworld
1.6       dillon    162:        make buildkernel KERNCONF=<KERNELNAME>
1.7       dillon    163:        make installkernel KERNCONF=<KERNELNAME>
1.6       dillon    164:        make installworld
                    165: 
1.16      swildner  166: You will also want to run the 'upgrade' target to upgrade your /etc and the
                    167: rest of your system.  The upgrade target is aware of stale files created by
                    168: older DragonFly installations and should delete them automatically.
1.7       dillon    169: 
                    170:        make upgrade
                    171: 
1.16      swildner  172: NOTE! Never do a 'make upgrade' before 'make installworld' has been run.
                    173: Doing so might leave your system in an unusable state.
                    174: 
1.7       dillon    175: If you are using 'config' manually from /usr/src/sys/i386/conf/BLAH, note 
                    176: that the build will use the current DragonFly environment rather then
                    177: the post-build environment from the last buildworld.   For this reason manual
                    178: configs are discouraged.  The proper way to build a kernel is to use the
                    179: 'buildkernel' or 'quickkernel' target in /usr/src.
                    180: 
                    181: Once you've done a full build of the world and kernel you can do incremental
                    182: upgrades of either by using the 'quickworld' and 'quickkernel' targets
                    183: instead of 'buildworld' and 'buildkernel'.  If you have any problems with
                    184: the quick targets, try doing a cvsup, cvs update, and then a full buildworld
                    185: and buildkernel as shown above, before asking for help.
1.1       dillon    186: 
1.2       asmodai   187: > Kerberos IV
                    188: -------------
1.1       dillon    189: 
1.2       asmodai   190: Kerberos IV (eBones) was removed from the tree, please consider moving to
                    191: Kerberos 5 (Heimdal).
1.1       dillon    192: 
1.3       dillon    193: > FreeBSD and DragonFly ports
                    194: -----------------------------
                    195: 
                    196: DragonFly will eventually have its own package management system but at the
                    197: moment we leverage off of the FreeBSD ports system.  You should maintain
                    198: /usr/ports from the FreeBSD cvs repository via cvsup just like you do now.
                    199: 
1.5       dillon    200: DragonFly has its own 'port overrides' hierarchy in /usr/dfports.  You can
1.3       dillon    201: check this out of the DragonFly cvs repository using:
                    202: 
                    203: cd /usr
1.13      swildner  204: cvs -R -d /home/dcvs checkout -P dfports
1.3       dillon    205: 
                    206: Be sure that you have installed 'relpath' from the DragonFly sources
                    207: (/usr/src/usr.bin/relpath) as well as the updated /usr/share/mk files from
                    208: /usr/src/share/mk.  As a test you can cd into /usr/ports/sysutils/cpdup and
                    209: build the port.  Dragonfly should contain an override and you should see a
                    210: warning message that the DragonFly override is being build instead when you
                    211: build it from the FreeBSD ports.
1.1       dillon    212: