UPDATING.64BTT

   1 # -------+---------+---------+---------+---------+---------+---------+---------+
   2
   3    The FreeBSD/sparc64 port has now changed time_t from 32-bits to 64-bits.
   4    This file explains the exact steps that users should follow to update their
   5    sparc64 systems for this change.  People running FreeBSD on other types of
   6    hardware, such as CPU's from Intel or AMD, can ignore this file.  For now,
   7    this change is only happening for people running FreeBSD on Sparc hardware.
   8
   9 # -------+---------+---------+---------+---------+---------+---------+---------+
  10 # Copyright (c) 2004  - Garance Alistair Drosehn <gad@FreeBSD.org>.
  11 #
  12 # All rights reserved.
  13 #
  14 #  Redistribution, publication, translation and use, with or without
  15 #  modification, in full or in part, in any form or format of this
  16 #  document are permitted without further permission from the author.
  17 #
  18 #  THIS DOCUMENT IS PROVIDED BY GARANCE DROSEHN ``AS IS'' AND ANY EXPRESS
  19 #  OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  20 #  WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  21 #  DISCLAIMED.  IN NO EVENT SHALL GARANCE DROSEHN BE LIABLE FOR ANY DIRECT,
  22 #  INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  23 #  (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
  24 #  SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25 #  HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  26 #  STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
  27 #  IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 #  POSSIBILITY OF SUCH DAMAGE.
  29 #
  30 # -------+---------+---------+---------+---------+---------+---------+---------+
  31 # $FreeBSD$
  32 # -------+---------+---------+---------+---------+---------+---------+---------+
  33
  34 If you are in too much of a hurry to read this file, then this is not the
  35 time for you to upgrade to a 64-bit time_t.  Period.  Stick with a system
  36 using 32-bit time_t until you have plenty of time to perform an upgrade.
  37
  38 This statement is true even if you have performed a thousand system upgrades
  39 in the past, and you are certain that you know everything there is to know
  40 about upgrades.  This upgrade *will* take you more time than previous system
  41 upgrades, simply because you must recompile at least some of your ports after
  42 upgrading the base system.
  43
  44 Do not start this update unless you have the extra time.
  45
  46 As of March 10th, the official value for time_t on sparc64 has changed to
  47 be 64-bits.  If you really must build system with 32-bit time_t's, then it
  48 would be best to stick with a snapshot of current from before March 10th.
  49 With src snapshots after that point, there will soon be ports which assume
  50 you have a 64-bit time_t based on the value of __FreeBSD_version.
  51
  52 If you are ready to upgrade, then *READ THIS ENTIRE DOCUMENT* at least
  53 once before starting the upgrade.
  54
  55 # -------+---------+---------+---------+---------+---------+---------+---------+
  56
  57 This is a major change.  This change will *not* be backwards-compatible.
  58 Any programs which call system-routines for handling time-values will
  59 have to be recompiled after this change is made.
  60
  61 Because this change is not backwards-compatible, it is important that
  62 the following steps be used when upgrading the system.  "Shortcuts" that
  63 have worked for EVERY SINGLE UPGRADE YOU HAVE EVER DONE IN YOUR LIFE are
  64 probably irrelevant.  This change is more disruptive than most of the
  65 changes which are normally done on freebsd.
  66
  67 These steps are designed to minimize the chance of you running into any
  68 trouble.  We can not guarantee that these steps will avoid all possible
  69 problems, but if you ignore these steps you are very likely to run into
  70 some very painful and time-consuming headaches when upgrading.
  71
  72 Step Pre-1:  Update to a recent snapshot of -current, and first build
  73              that as a system with 32-bit time_t.  To do this, edit
  74              the file  /usr/src/sys/sparc64/include/_types.h
  75              find the line:
  76                typedef  __int64_t       __time_t;       /* time()... */
  77              and change '__int64_t' to '__int32_t'
  78 Step Pre-2:  Install that system, using whatever steps you normally
  79              use, and make sure that installation seems to work okay.
  80 Step Pre-3:  While still running that 32-bit time_t system, it would
  81              probably be a good idea to cvsup your ports tree, and
  82              then upgrade portupgrade (if you use it) and upgrade any
  83              shells that you use.  Eg:
  84                   portupgrade -Rr -f ruby portupgrade
  85                   portupgrade -Rr -f bash
  86              That way you know you have the latest versions, and you
  87              will also know you have the most-recent distfiles on
  88              your machine.
  89
  90 Step Pre-4:  For sparc64 machines which need DHCP:
  91              The 'dhclient' in the base system is known to be unreliable
  92              on a system which is upgraded to 64-bit time_t's.  It may
  93              work for you, but it probably will not.
  94              As of March 10th 2004, we have no fix for that.
  95              However, the net/isc-dhcp3-client port does seem to work.
  96              IF your machine needs DHCP, then you should probably install
  97              that port and make sure you can get it working *before* you
  98              make the change to use 64-bit time_t's.
  99
 100 Step Pre-4:  For people using database-related ports:
 101              Ports like PostgreSQL may change how they store data after
 102              they are recompiled for 64-bTT.  So, you may have to do a
 103              full dump of your data while you still have a 32-bTT system,
 104              and do a matching initdb/restore of your data after the port
 105              has been recompiled on the upgraded 64-bTT system.
 106
 107 After you have built and installed that src-snapshot with 32-bit time_t's,
 108      edit the file  /usr/src/sys/sparc64/include/_types.h
 109      find the line:
 110         typedef __int32_t       __time_t;       /* time()... */
 111      and change '__int32_t' back to '__int64_t'
 112
 113      For best results, do NOT make any other changes.  Do NOT cvsup the
 114      source tree trying to pick up any other changes.  At this point you
 115      know that you have a source tree that does work for your system, so
 116      stick with that source tree (except for making the above 1-line
 117      change, of course).
 118
 119      At one point in my testing, I did do a 'cvsup' which just happened
 120      to pull in one bad commit that broke 'make buildworld', and a second
 121      bad commit that broke 'make installworld'.  Believe me, you REALLY
 122      REALLY do *not* want to risk problems like that!
 123
 124      I am not suggesting that you have to do two whole buildworld/
 125      installworld cycles in a single day.  You could easily wait a few
 126      days, or even a week between them.  What I am suggesting is that
 127      you should not 'cvsup' your sources inbetween the two buildworlds.
 128
 129 And then follow these steps to build and install the 64-bit time_t system:
 130
 131     cd /usr/src                   #-  1.
 132     make cleanworld               #-  2.  or 'rm -Rf /usr/obj/usr/src/*'
 133     make buildworld               #-  3.
 134     make buildkernel              #-  4.  Add KERNCONF if you usually do.
 135     NEWSPARC_TIMETYPE=__int64_t   #-  5.  (Used by a safety-check done
 136     export NEWSPARC_TIMETYPE      #-  5a.   by installkernel)
 137     make installkernel            #-  6.  Add KERNCONF if you usually do.
 138     mergemaster -p                #-  7.
 139
 140         # - - A section required for installs over NFS-mounts  - - #
 141     ifconfig -a                   #-  NFS 8a.       See note below.
 142     shutdown now                  #-  NFS 8b.  NOT 'shutdown -r now'
 143     cd /usr/src                   #-  NFS 8c.
 144     sh installworld_oldk           #-  NFS 8d.       See note below.
 145         # - -        End of this section for NFS-mounts        - - #
 146
 147     reboot                        #-  9.  MUST go into single-user mode
 148
 149 For many upgrades, it is true that you can "cheat" at this point, and
 150 get away without actually going into single-user mode straight from
 151 the reboot.  But for this upgrade, you REALLY MUST start up straight
 152 into single user mode.  So, reboot the machine, type a space (or
 153 anything other than 'Enter') when the boot-loader is counting down.
 154 And then:
 155
 156       boot -s                            #- 10.  (command to boot-loader)
 157
 158 The system will ask you if you want to use /bin/sh or some other shell.
 159 For this upgrade, just hit enter, even if you usually prefer like some
 160 other shell instead of /bin/sh.
 161
 162       fsck -p                            #- 11.
 163          # - - A section required for installs over NFS-mounts  - - #
 164       PATH=/boot/kernel/bin:$PATH        #- NFS 12.
 165          # - -        End of this section for NFS-mounts        - - #
 166       mount -a -t ufs                    #- 13.
 167       swapon -a                          #- 14.
 168          # - - A section required for installs over NFS-mounts  - - #
 169       ifconfig hme0 inet ....            #- NFS 15a.   See note below.
 170       mount_nfs host:srcdir /usr/src     #- NFS 15b.   See note below.
 171       mount_nfs host:objdir /usr/obj     #- NFS 15c.
 172          # - -        End of this section for NFS-mounts        - - #
 173       cd /usr/src                        #- 16.
 174       sh installworld_newk               #- 17.  Might want to add -S
 175       mergemaster                        #- 18.
 176       rm -f /var/db/dhclient.leases      #- 19.  If this host uses DHCP
 177       reboot                             #- 20.
 178
 179 At this point, you should be up-and-running on a system that has 64-bit
 180 values for time_t.  You will have to rebuild anything which depends on
 181 time_t.  Later in this file is a suggested order for upgrading ports.
 182
 183 If you have a lot of ports which start up daemons or do other processing
 184 at system-startup, then you might want to have this reboot also go into
 185 single-user mode for upgrading all of the ports.  In my case, I've always
 186 done a standard reboot at this point and did not run into problems, but
 187 then I only have 25 ports installed on my SPARC64 system.
 188
 189 Aside: It is slightly more reasonable to use the 'reboot' command, although
 190 you may be more familar with using 'shutdown -r now'.  The shutdown command
 191 just turns around and executes '/sbin/reboot', and with this upgrade it is
 192 best to avoid such redirection.
 193
 194 # -------+---------+---------  Notes on the above   -------+---------+---------+
 195
 196 General notes on NFS issues:
 197
 198   For this upgrade to 64-bit time_t's, the change is so disruptive that I
 199   couldn't get NFS-mounts to work if I booted a "32-bit time_t system"
 200   (ie: 32-bit versions of /bin, /sbin, /lib, ...) on a 64-bit kernel.  So,
 201   I added the installworld_oldk script.  This script does two things:
 202      1)  Creates a mini-/bin inside /boot/kernel.
 203      2)  Does a minimal installworld (while still on the old kernel),
 204          thus making it possible for NFS-mounts to work when you reboot.
 205
 206   The first half is a step that would be perfectly safe to do, for any
 207   upgrade (including non-NFS ones), at any time.  It is a generally safe
 208   and interesting idea, although it really should be implemented as an
 209   official target in /usr/src/Makefile to be done right.
 210
 211   The second half would USUALLY be a bad idea to do, but I think it's the
 212   only way I can get this specific upgrade to work for people that install
 213   from NFS-mounted directories.  It is bad because you are clobbering parts
 214   of your system even though (in the usual case) you would not know that
 215   the new kernel actually works on your system.  It also does not do a
 216   full-install, so you end up booting into a system which is part old-
 217   world, and part new-world.  It looks like we can get away with that for
 218   this upgrade, but the tactic would be too risky for "standard upgrades".
 219
 220   These instructions assume that you are already familiar with how to do
 221   installations over NFS-mounted partitions.  If you are not, you might
 222   want to read other references, such as 'man development'.
 223
 224 Notes on step NFS 8a:     ifconfig -a
 225
 226   This shows to the configuration of all your ethernet interfaces.  Write
 227   down the IP address and netmask of your main interface.  This is
 228   particularly important if the machine obtains its address via DHCP.
 229   You will not be running dhclient after the reboot in step 8, so just
 230   re-use the IP address that the machine is using for the present reboot.
 231
 232 Notes on step NFS 8b:     shutdown now
 233
 234   This will drop you into single-user mode, without rebooting.  It
 235   will ask if you want to use /bin/sh for your shell.  You do.
 236
 237 Notes on step NFS 8d:     sh installworld_oldk
 238
 239   Note that this script only installs *part* of the new world.  You will
 240   still have to reboot into single-user mode and do the full installworld.
 241   The installworld_oldk script will ask you if you want to build a
 242   mini-/bin.  For this upgrade, you should say "yes".
 243
 244 Notes on step NFS 15a:
 245   On my Ultra-10, I have the 'hme0' device as my ethernet card.  The output
 246   of 'ifconfig -a' (from step 'NFS 7a') included the lines:
 247
 248       hme0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500
 249             inet 192.168.1.18 netmask 0xffffffe0 broadcast 192.168.1.31
 250
 251   So for this step, I typed in the command:
 252       ifconfig hme0 inet 192.168.1.18 netmask 0xffffff00
 253
 254 Notes on step NFS 15b:    mount_nfs
 255
 256   At this step, you may need to specify the host as an IP address instead
 257   of a hostname, because the machine will only be able to resolve hostnames
 258   that are in /etc/hosts.
 259
 260   In my case,  I found it easier to create a source file ahead of time
 261   which included the ifconfig and mount_nfs commands that I knew I would
 262   need, and then I just sourced that file after rebooting into single user
 263   mode.  If you made such a source file and put it in your root partition,
 264   perhaps under /boot, then that file could also include all of the steps
 265   from 11 through 15c.
 266
 267   Also, it is best use the 'mount_nfs' command, instead of 'mount -t nfs'.
 268   If you use the 'mount' command for NFS mounts, it will turn around and
 269   directly execute /sbin/mount_nfs, and that is not desirable in this case.
 270
 271 Notes on step 17:         sh installworld_newk
 272
 273   This script will do some setup work, and then ask you if want it to run
 274   'make installworld'.  Most people should just answer "y" (yes) to that
 275   prompt.  You can avoid the prompt by including "-y" or "-n" on the
 276   command.  If you say "n" (no), then it will tell you what commands
 277   you must type to do the actual installworld.
 278
 279   The script also recognizes a "-S" parameter, which causes it to use
 280   symlinks instead of making copies of programs used by the installation
 281   process.  This option will cause less filespace to be used up in /tmp,
 282   but it might be slower in some cases (especially for installs using
 283   an NFS-mounted directory for /usr/obj).
 284
 285   Both this script and the installworld_oldk script also recognize a "-M"
 286   option.  This option causes the script to use the absolute minimum PATH
 287   setting that "should" be needed to complete an install.  This option is
 288   mainly just for debugging the scripts, though.  If you request the
 289   minimum PATH, and some important file was NOT properly copied, then the
 290   installworld will immediately die at that point. This might be painful.
 291   Without "-M", the same oversight would mean that you will run the wrong
 292   *version* of the command, but that older version might actually work
 293   perfectly fine.  I did all my testing with "-M" to make sure I had
 294   found all important programs, but there is probably no advantage for
 295   using it for standard system upgrades.  Also, if there are no important
 296   files overlooked, then "-M" will not make any difference at all.
 297
 298 # -------+---------+---------+  Upgrading Ports  +---------+---------+---------+
 299
 300 Similar to the recommendation for the upgrading the system, I suggest that
 301 you do not 'cvsup' your local copy of the ports collection before trying to
 302 rebuild everything for 64-bit time_t.  For one thing, you will have a cvsup
 303 compiled for 32-bTT (32-bit time_t's), and that will not work well on a
 304 system which is using 64-bTT.  You might find that you have to 'cvsup' for
 305 some ports, but you will need to get a 64-bTT version of cvsup before you
 306 can do that.
 307
 308 One tactic to use for upgrading ports is to rebuild your already-installed
 309 ports one-at-a-time.  If you want to do that, and if you use portupgrade
 310 to upgrade your ports, then I suggest the first thing you should do is:
 311
 312     portupgrade -Rr -f ruby portupgrade          #- Ports 1.
 313         Aside: if you get an error about the "ruby-rdoc" port,
 314         then enter:    pkg_deinstall ruby-rdoc
 315         and repeat the original command.
 316     portupgrade -Rr -f bash                      #- Ports 2.
 317         If you have 'bash' installed, or include any other shells
 318         which you have installed from the ports collection.  If
 319         your session is *using* one of these shells, then logout
 320         and log back in after recompiling that shell.
 321     portupgrade -Rr -f ezm3 cvsup-without-gui    #- Ports 3 (maybe).
 322         If you want to rebuild a 64-bit time_t version of cvsup.
 323         Note: ezm3 (modula-3) needs a patch to work correctly after the
 324         change to 64-BTT.  That fix has not been commited to the port
 325         yet [as of Mar 10th], but hopefully it will be commited soon.
 326
 327 There are pre-built packages available for ezm3 and cvsup-without-gui on
 328 the new 64-bTT systems.  This ezm3 package *does* include the necessarily
 329 patch.  These files are available on the standard ftp servers for FreeBSD.
 330 If you have previous versions installed, then remove them with:
 331
 332     pkg_delete cvsup\*
 333     pkg_delete ezm3\*
 334         If you get warnings about "unable to completely remove" some
 335         lib/m3 directories when deleting ezm3, then also enter:
 336     rm -rf /usr/local/lib/m3
 337
 338 You can install the new packages with:
 339
 340     pkg_add ftp://ftp3.FreeBSD.org/pub/FreeBSD/ports/local-distfiles/gad/ez...
 341     pkg_add ftp://ftp3.FreeBSD.org/pub/FreeBSD/ports/local-distfiles/gad/cv...
 342         Replacing "ez..." with "ezm3-64btt-1.1_1.tbz" and "cv..."
 343         with "cvsup-without-gui-64btt-16.1h.tbz".  You can also use
 344         some other standard ftp server, instead of ftp3.FreeBSD.org.
 345
 346     "Now look over all the other ports you have installed, and
 347     re-compile everything that probably needs to be recompiled".
 348
 349 If you are going to do it piecemeal, the next ports to force-rebuild would
 350 probably be languages like perl and python, if you have them installed.
 351 After that, force-rebuild the ports like autoconf and automake, if you
 352 have them installed.  Or you might want to play it safe at this point,
 353 and simply recompile *every* port that you have installed.
 354
 355 A different tactic to use for ports is to remove *all* ports before you
 356 do the installkernel/installworld step (while you're still on a 32-bTT
 357 system).  Then, once you're up on the 64-bTT system, start making them
 358 one-by-one.  If you follow this tactic, you might want to save the output
 359 of a 'pkg_info' command before you start removing ports.
 360
 361 # -------+---------+---------+---------+---------+---------+---------+---------+
 362
 363 If you run into problems when making this change, please report them to
 364 the mailing list freebsd-sparc64@FreeBSD.org .
 365
 366 # -------+---------+---------+---------+---------+---------+---------+---------+
 367 #  Notice that the following command can be useful in some settings:
 368                grep '#\- ' UPDATING.64BTT