1dnl 2dnl $OpenBSD: m4.common,v 1.137 2023/10/19 18:39:46 kn Exp $ 3dnl 4dnl Copyright (c) 2004 Todd T. Fries <todd@OpenBSD.org> 5dnl 6dnl Permission to use, copy, modify, and distribute this software for any 7dnl purpose with or without fee is hereby granted, provided that the above 8dnl copyright notice and this permission notice appear in all copies. 9dnl 10dnl THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 11dnl WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 12dnl MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 13dnl ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 14dnl WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 15dnl ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 16dnl OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 17dnl 18dnl simulate an include path with a macro 'includeit'. 19define(`includeit',`sinclude('INCLUDE/`$1)sinclude('INCLUDE/../`$1)')dnl 20dnl 21dnl 22dnl TopPart 23dnl Describes the beginning of the distribution files listing. 24dnl 25define(`TopPart', 26`The MACHINE-specific portion of the OpenBSD OSREV release is found in the 27"MACHINE" subdirectory of the distribution. That subdirectory is laid 28out as follows: 29 30.../OSREV/MACHINE/ 31 32 INSTALL.MACHINE Installation notes; this file. 33 34 SHA256 Output of the cksum(1) program using the option 35 -a sha256, usable for verification of the 36 correctness of downloaded files. 37 38 SHA256.sig The above file, signed with the OpenBSD signing key 39 for the OSREV release, usable for verification of the 40 integrity of the above file, and thus of the 41 downloaded files.')dnl 42dnl 43dnl Change the quote. There were too many `word' situations that would 44dnl have to have been changed to ``word''. The quote gets changed to 45dnl {:- and -:}. It can really be anything, but it needs to be unique. 46dnl 47changequote(`{:-',`-:}')dnl 48dnl 49dnl Conventions when editing: 50dnl o base`'OSrev is required because if it appears as baseOSrev the 51dnl defined value OSrev does not get substituted. Same goes for MACHINE, 52dnl MACHINE_ARCH and OSREV, assigned as cmd line parameters to m4 in the 53dnl Makefile. 54dnl o `include', `define' and `shift' is required as these three words 55dnl are m4 reserved words that evaluate to an empty string if not quoted. 56dnl 57dnl 58dnl ========== Distribution files description 59dnl (usually used by arch/contents) 60dnl 61dnl printsize(value) 62dnl 63dnl Prints a size in KB if it is less than 10^6, in MB otherwise. 64dnl The size is rounded down (this means you can still get 0.9 MB for 65dnl a size between 1,000,000 and 1,048,576 bytes). 66dnl Used by showsize() below. 67dnl 68define({:-printsize-:},{:-ifelse(substr($1,6),,dnl 69eval($1/1024).eval($1*10/1024%10) KB,dnl 70eval($1/1024/1024).eval($1/1024*10/1024%10) MB)-:})dnl 71dnl 72dnl showsize(gzipped size, uncompressed size) 73dnl 74dnl If both the 1st and the 2nd argument exist, show the sizes. 75dnl Otherwise, evaluate to NULL. 76dnl showsize() must not be on a new line. It creates its own new line if 77dnl there are sizes to display, otherwise, evaluates to NULL 78dnl 79dnl XXX fix to allow - empty 1st arg, for files uncompressed 80dnl - empty 2nd arg, for files where only compressed size 81dnl is known 82dnl 83define({:-showsize-:},{:-ifelse(X$1,X,,X$2,X,,X,X,{:- 84 [ printsize($1) gzipped, printsize($2) uncompressed ]-:})-:})dnl 85dnl 86dnl 87dnl 88dnl DistributionDescription( number of sets ) 89dnl Header paragraph before the individual sets descriptions. 90dnl 91define({:-DistributionDescription-:}, 92{:-The OpenBSD/MACHINE binary distribution sets contain the binaries which 93comprise the OpenBSD OSREV release for MACHINE systems. There are $1 94binary distribution sets. The binary distribution sets can be found in 95the "MACHINE" subdirectory of the OpenBSD OSREV distribution tree, 96and are as follows:-:})dnl 97dnl 98dnl 99dnl OpenBSDbase( compressed size, uncompressed size ) 100dnl Describes baseXX.tgz. 101dnl 102define({:-OpenBSDbase-:}, 103{:- base{:--:}OSrev The OpenBSD/MACHINE OSREV base binary distribution. You MUST 104 install this distribution set. It contains the base OpenBSD 105 utilities that are necessary for the system to run and be 106 minimally functional. This includes parts of the toolchain 107 required to relink a kernel. 108 ifelse(MDSO,,{:-It excludes everything described below.-:},{:-It includes shared library support, and excludes everything 109 described below.-:})showsize($1,$2)-:})dnl 110dnl 111dnl 112dnl OpenBSDcomp( compressed size, uncompressed size ) 113dnl Describes compXX.tgz. 114dnl 115define({:-OpenBSDcomp-:}, 116{:- comp{:--:}OSrev The OpenBSD/MACHINE Compiler tools. All of the tools relating 117 to C and C++ are supported. This set includes the system 118 {:-include-:} files (/usr/{:-include-:}), the compiler 119 toolchain, and the various system libraries{:--:}ifelse(MDSO,,.,{:- (except the 120 shared libraries, which are included as part of the base set).-:}) 121 This set also includes the manual pages for all of the 122 utilities it contains, as well as the system call and library 123 manual pages.showsize($1,$2)-:})dnl 124dnl 125dnl 126dnl OpenBSDgame( compressed size, uncompressed size ) 127dnl Describes gameXX.tgz. 128dnl 129define({:-OpenBSDgame-:}, 130{:- game{:--:}OSrev This set includes the games and their manual pages.showsize($1,$2)-:})dnl 131dnl 132dnl 133dnl OpenBSDman( compressed size, uncompressed size ) 134dnl Describes manXX.tgz. 135dnl 136define({:-OpenBSDman-:}, 137{:- man{:--:}OSrev This set includes all of the manual pages for the binaries 138 and other software contained in the base set. 139 Note that it does not {:-include-:} any of the manual pages 140 that are included in the other sets.showsize($1,$2)-:})dnl 141dnl 142dnl 143dnl OpenBSDxbase( compressed size, uncompressed size ) 144dnl Describes xbaseXX.tgz. 145dnl 146define({:-OpenBSDxbase-:}, 147{:- xbase{:--:}OSrev This set includes the base X distribution. This includes 148 programs, headers and libraries.showsize($1,$2)-:})dnl 149dnl 150dnl 151dnl OpenBSDxshare( compressed size, uncompressed size ) 152dnl Describes xshareXX.tgz. 153dnl 154define({:-OpenBSDxshare-:}, 155{:- xshare{:--:}OSrev This set includes all text files equivalent between all 156 architectures.showsize($1,$2)-:})dnl 157dnl 158dnl 159dnl OpenBSDxfont( compressed size, uncompressed size ) 160dnl Describes xfontXX.tgz. 161dnl 162define({:-OpenBSDxfont-:}, 163{:- xfont{:--:}OSrev This set includes all of the X fonts.showsize($1,$2)-:})dnl 164dnl 165dnl 166dnl OpenBSDxserv(compressed size,uncompressed size,optional extra notes) 167dnl Describes xservXX.tgz. 168dnl 169define({:-OpenBSDxserv-:}, 170{:- xserv{:--:}OSrev This set includes all of the X servers.$3{:--:}showsize($1,$2)-:})dnl 171dnl 172dnl 173dnl Floppy and bootable cdrom stuff 174dnl 175define({:-OpenBSDfloppy-:}, 176{:- floppy{:--:}OSrev.img The standard MACHINE boot and installation floppy; 177 see below.-:})dnl 178dnl 179define({:-OpenBSDinstalliso-:}, 180{:- install{:--:}OSrev.iso The MACHINE boot and installation CD-ROM image, 181 which contains the base and X sets, so that install 182 or upgrade can be done without network connectivity.-:})dnl 183define({:-OpenBSDcd-:}, 184{:- cd{:--:}OSrev.iso A simple bootable filesystem image consisting of the 185 bsd.rd installation kernel, suitable to be used 186 as a bootable CD-ROM image, but will require the base 187 and X sets be found via another media or network.-:})dnl 188dnl 189dnl OpenBSDfloppydesc(number of floppies, Article, plural) 190dnl 191dnl Describe what the boot floppy/ies contain and how they may be used. 192dnl Use as: OpenBSDfloppydesc(single,The) or OpenBSDfloppydesc(three,Each,s) 193define({:-OpenBSDfloppydesc-:}, 194{:-Bootable installation/upgrade floppy image$3: 195 196 The $1 floppy image$3 can be copied to a floppy using rawrite.exe, 197 ntrw.exe, or "dd", as described later in this document. 198 $2 floppy image is a bootable install floppy which can be used 199 both to install and to upgrade OpenBSD to the current version. 200 It is also useful for maintenance and disaster recovery.-:})dnl 201dnl 202dnl 203dnl A few extra straightforward macros describing more components. 204dnl 205define({:-OpenBSDdistsets-:}, 206{:- *.tgz MACHINE binary distribution sets; see below.-:})dnl 207dnl 208define({:-OpenBSDbsd-:}, 209{:- bsd A stock GENERIC MACHINE kernel which will be 210 installed on your system during the install.-:})dnl 211dnl 212define({:-OpenBSDbsdmp-:}, 213{:- bsd.mp A stock GENERIC.MP MACHINE kernel, with support for 214 multiprocessor machines, which can be used instead 215 of the GENERIC kernel after the install.-:})dnl 216dnl 217define({:-OpenBSDrd-:}, 218{:- bsd.rd A compressed RAMDISK kernel; the embedded 219 filesystem contains the installation tools. 220 Used for simple installation from a pre-existing 221 system.-:})dnl 222dnl 223define({:-OpenBSDminiroot-:}, 224{:- miniroot{:--:}OSrev.img A miniroot filesystem image to be used if you 225 for some reason can't or don't want to use the 226 ramdisk installation method.-:})dnl 227dnl 228define({:-OpenBSDinstallfs-:}, 229{:- install{:--:}OSrev.img A boot and installation image which contains 230 the base and X sets. An install or upgrade can be 231 done with a USB key without network connectivity.-:})dnl 232dnl 233dnl 234dnl ========== Various Install Instructions 235dnl (usually used by arch/install) 236dnl 237dnl OpenBSDInstallPrelude(troublesome disk types) 238dnl 239dnl Installation introduction. Warns about disk geometry hell if argument 240dnl is not empty. 241define({:-OpenBSDInstallPrelude-:}, 242{:-Installing OpenBSD is a relatively simple process. If you take your time 243and are careful to read the information presented by the installer, you 244shouldn't have any trouble.ifelse(X$1,X,,{:- 245 246If the disks connected to your machine are $1, 247it is recommended that you know their geometry, i.e. the sector size (note 248that sector sizes other than 512 bytes are not currently supported), the 249number of sectors per track, the number of tracks per cylinder (also known 250as the number of heads), and the number of cylinders on the disk. The 251OpenBSD kernel will try to discover these parameters on its own, and if it 252can it will print them at boot time. If possible, you should use the 253parameters it prints. (You might not be able to because you're sharing your 254disk with another operating system, or because your disk is old enough that 255the kernel can't figure out its geometry.)-:})-:})dnl 256dnl 257dnl OpenBSDInstallPart2 258dnl Describes the beginning of the installation process, once the 259dnl installation media is ready. 260define({:-OpenBSDInstallPart2-:}, 261{:-You should now be ready to install OpenBSD. 262 263The following is a walk-through of the steps you will take while getting 264OpenBSD installed on your hard disk. 265 266The installation procedure is designed to gather as much information about 267your system setup as possible at the beginning, so that no human interaction 268is required as soon as the questions are over. 269 270The order of these questions might be quite disconcerting if you are used to 271other installation procedures, including older OpenBSD versions. 272 273If any question has a default answer, it will be displayed in brackets ("[]") 274after the question. If you wish to stop the installation, you may hit 275Control-C at any time, but if you do, you'll have to begin the installation 276process again from scratch. Using Control-Z to suspend the process may be a 277better option, or at any prompt enter "!" to get a shell, from which "exit" 278will return you back to that prompt. 279-:})dnl 280dnl 281dnl OpenBSDInstallPart3(warn geometry, disk type, disk type, disk type) 282dnl 283dnl Describes the boot of the ramdisk. 284dnl Describes the serial terminal setup. 285define({:-OpenBSDInstallPart3-:}, 286{:- Once the kernel has loaded, you will be presented with the 287 OpenBSD kernel boot messages which contain information about 288 the hardware that was detected and supported by OpenBSD. 289 290dnl dot.profile 291 After the kernel is done initializing, you will be asked whether 292 you wish to do an "(I)nstall", "(U)pgrade" or an "(A)utoinstall". 293 Enter "I" for a fresh install or "U" to upgrade an existing 294 installation. Enter "A" to start an unattended installation 295 where all of your answers are supplied in a response file (more 296 on that in "Preparing an unattended installation of OpenBSD"). 297 298dnl install.sub set_term 299ifelse(MDX,, 300{:- You will next be asked for your terminal type.-:}, 301{:- If you are connected with a serial console, you will next be 302 asked for your terminal type.-:})dnl 303 304 You should choose the terminal type from amongst those listed. 305 (If your terminal type is xterm, just use vt220).dnl 306ifelse(MDKBD,,,{:- 307 308 If you are connected using a glass console, you will next be 309 asked for your keyboard layout (the default being the US QWERTY 310 layout). Depending on your keyboard type, not all international 311 layouts may be supported; answering "?" (which, on QWERTY layouts, 312 is the key to the left of the right "sh{:--:}ift" key, shifted) will 313 display a list of supported layouts. 314 (If you do not need to change the keyboard layout, just press 315 enter.)-:})dnl 316-:})dnl 317dnl 318dnl OpenBSDInstallPart4 319dnl 320dnl Describes the beginning of the bsd.rd operation. 321dnl 322define({:-OpenBSDInstallPart4-:},dnl 323dnl install.sub (install) hostname 324{:- The first question you will be asked is the system hostname. 325 Reply with the name of the system, without any domain part. 326 327dnl install.sub (install) donetconfig 328 You will now be given an opportunity to configure the network. 329 The network configuration you enter (if any) can then be used to 330 do the install from another system using HTTP, and will also be 331 the configuration used by the system after the installation is 332 complete. 333 334dnl XXX add a MDVLAN feature and document vlan setup 335 The install program will give you a list of network interfaces you 336 can configure. For each network interface you select to configure, 337 you will be asked for: 338 339 - the symbolic host name to use (except for the first 340 interface setup, which will reuse the host name entered at the 341 beginning of the installation). 342 343 - the IPv4 settings: address and netmask. If the IP address 344 should be obtained from a DHCP server, simply enter "dhcp" 345 when asked for the address. 346 347 - the IPv6 settings (address, prefix length, and default router). 348 You may enter "autoconf" when asked for the address for the 349 interface to configure automatically via router solicitation 350 messages. 351 352 After all interfaces have been configured, if there have been 353 any IPv4 interfaces set up, you will be asked for the IPv4 default 354 route. This step is skipped if you only have one IPv4 interface 355 setup, and it is configured with DHCP. 356 357 The install program will also ask you for your DNS domain name, 358 and the domain name servers, unless this information has 359 already been obtained from a DHCP server during interface setup. 360 361dnl install.sub (install) askpassword root 362 You will then be asked to enter the initial root password 363 of the system, twice. 364 365 Although the install program will only check that the two 366 passwords match, you should make sure to use a strong password. 367 As a minimum, the password should be at least eight characters 368 long and a mixture of both lower and uppercase letters, numbers 369 and punctuation characters. 370 371dnl install.sub (install) questions(): sshd/ntpd 372 You will then be asked whether you want to start sshd(8) by 373 default. 374dnl 375dnl install.sub (install) questions(): MDXAPERTURE 376ifelse(MDXAPERTURE,,,{:- 377 You will next be asked whether you intend to run the X Window 378 System on your machine. The install program needs to know 379 this, to change a configuration setting controlling whether 380 the X server will be able to access the xf86(4) driver; it 381 is not necessary to answer "y" to this question if you only 382 intend to run X client programs on a remote display. 383-:})dnl 384dnl install.sub (install) questions(): MDXDM 385ifelse(MDXDM,,, 386{:-ifelse(MDXAPERTURE,,{:- 387 Since the X Window System can run on OpenBSD/MACHINE 388 without the need for a configuration file, you will get asked-:}, 389{:- If you answered "y" to this question, you will get asked-:}) 390 whether you want to start xenodm(1) on boot. 391-:})dnl 392dnl install.sub (install) questions(): serial console setup 393ifelse(MDSERCONS,,,{:- 394 If you are installing using a serial console, and since by default, 395 the OpenBSD/MACHINE installation will only start terminals on 396 the primary display device, the installation program will ask you 397 whether you want to also enable an additional terminal on that 398 line, and will allow you to select the line speed. 399-:})dnl 400 401dnl install.sub (install) user_setup() 402 You will now be given the possibility to set up a user account 403 on the forthcoming system. This user will be added to the 404 "wheel" group. 405 406 Enter the desired login name, or "n" if you do not want to 407 add a user account at this point. Valid login names are 408 sequences of digits and lowercase letters, and must start 409 with a lowercase letter. If the login name matches this 410 criteria, and doesn't conflict with any of the administrative 411 user accounts (such as "root", "daemon" or "ftp"), you 412 will be prompted for the user's descriptive name, as well 413 as its password, twice. 414 415 As for the root password earlier, the install program will only 416 check that the two passwords match, but you should make sure to 417 use a strong password here as well. 418 419 If you have chosen to set up a user account, and you had chosen 420 to start sshd(8) on boot, you will be asked if you want to allow 421 sshd(8) logins as root. 422dnl install.sub (install) set_timezone 423ifelse(MDTZ,,, 424{:- 425 Depending on the installation media you are using, you may now 426 be given the opportunity to configure the time zone your system 427 will use. If the installation program skips this question, do 428 not be alarmed: the time zone will be configured at the end of 429 the installation. 430-:})dnl 431dnl install.sh ask whether to use DUIDs before the md_prep_disklabel loop 432 The installation program will now tell you which disks it can 433 install on, and ask you which it should use. 434 435 Reply with the name of your root disk.ifelse(MDBOOTSR,,,{:- 436 437 You will be given the possibility to encrypt the contents of that 438 disk with a passphrase or a key disk.-:})dnl 439-:})dnl 440dnl install.sh md_prep_disklabel loop 441dnl 442dnl OpenBSDInstallMBRPart1 443dnl Describes MBR partitioning. So much to save four lines of text 444dnl duplicated 5 times. 445dnl 446define({:-OpenBSDInstallMBRPart1-:}, 447{:- Disks on OpenBSD/MACHINE are partitioned using either "MBR" 448 or "GPT" partitioning schemes. You will need to create one 449 disk partition in which the OpenBSD filesystems will be created. 450-:})dnl 451dnl 452dnl OpenBSDInstallMBRPart2(needs OpenBSD partition active) 453dnl Describes fdisk invocation 454dnl 455define({:-OpenBSDInstallMBRPart2-:}, 456dnl install.md md_prep_fdisk 457{:- The installation program will ask you if you want to use the 458 whole disk for OpenBSD. If you don't need to or don't intend 459 to share the disk with other operating systems, answer "w" 460 here to use "MBR" partitioning or "g" to use "GPT" 461 partitioning. The installation program will then create a single 462 partition spanning the whole disk, dedicated to OpenBSD. 463 464 Otherwise, fdisk(8) will be invoked to let you to edit your 465 partitioning. The current partitions defined will be 466 displayed and you will be allowed to modify them, add new 467 partitions, and change which partition to boot from by default. 468 469ifelse(X$1,X,, 470{:- Note that you should make the OpenBSD partition the active 471 partition at least until the install has been completed. 472-:})dnl 473 After your OpenBSD partition has been created, dividing the 474 space into filesystems can follow. 475-:})dnl 476dnl 477dnl OpenBSDInstallPart5(mention about other OS partitions,mention about root 478dnl partition limitations) 479dnl Describes the disklabel operation 480dnl 481define({:-OpenBSDInstallPart5-:}, 482{:- The file system layout is stored in the OpenBSD disk label. Each 483 file system is stored in its own "disk label partition", which 484 is a subdivision of the OpenBSD disk partition you created. In 485 the text below, "partition" refers to these subdivisions. 486 487 You will be shown a default layout with the recommended file 488 systems. This default layout is based on the disk size. 489 490 You will be given the choice of accepting the proposed layout, 491 editing it, or creating your own custom layout. These 492 last two choices will invoke the disklabel(8) interactive editor, 493 allowing you to create your desired layout. 494 495 Within the editor, you will see at least a "c" partition of 496 fstype "unused". This represents the whole disk and cannot be 497 modified.$1 498 499 You must create partition "a" as a native OpenBSD partition, i.e. 500 one with "4.2BSD" as the fstype, to hold the root file system.$2 501 502 In addition to partition "a" you should create partition "b" with 503 fstype "swap", and native OpenBSD partitions to hold separate file 504 systems such as /usr, /tmp, /var, and /home. 505 506 You will need to provide a mount point for all partitions you 507 {:-define-:}. Partitions without mount points, or not of the 508 4.2BSD fstype, will neither be formatted nor mounted during the 509 installation. 510 511 For quick help while in the interactive editor, enter "?". 512 The "z" command (which deletes all partitions and starts with a 513 clean label), the "A" command (which performs the automatic 514 partition layout) and the "n" command (to change mount points) 515 are of particular interest. 516 517 Although the partitions' position and size are written in exact 518 sector values, you do not need a calculator to create your 519 partitions! Human-friendly units can be specified by adding "k", 520 "m" or "g" after any numbers to have them converted to kilobytes, 521 megabytes or gigabytes. Or you may specify a percentage of the 522 disk size using "%" as the suffix. 523 524 Enter "M" to view the entire manual page (see the info on the 525 "-E" flag). To exit the editor enter "q".-:})dnl 526dnl 527dnl OpenBSDInstallPart6(other installation sources) 528define({:-OpenBSDInstallPart6-:}, 529{:- After the layout has been saved, new filesystems will be 530 created on all partitions with mount points. 531 This will DESTROY ALL EXISTING DATA on those partitions. 532 533 After configuring your root disk, the installer will 534 return to the list of available disks to configure. 535 536 You can choose the other disks to use with OpenBSD in 537 any order, and will get to set up their layout similarly 538 to the root disk above. However, for non-root disks, 539 you will not be proposed a default partition layout. 540 541 When all your disks are configured, simply hit return 542 at the disk prompt. 543 544 After these preparatory steps have been completed, you will be 545 able to extract the distribution sets onto your system. There 546 are several install methods supported: 547 HTTP, $1or a local disk partition.-:})dnl 548dnl 549dnl Notes for various installation methods. 550dnl 551define({:-OpenBSDURLInstall-:}, 552{:- To install via HTTP: 553 To begin an HTTP install you will need the following 554 pieces of information: 555 1) Proxy server URL if you are using a URL-based HTTP 556 proxy (squid, CERN FTP, Apache 1.2 or higher). 557 You need to {:-define-:} a proxy if you are behind a 558 firewall that blocks outgoing HTTP connections 559 (assuming you have a proxy available to use). 560 2) The IP address (or hostname if you configured 561 DNS servers earlier in the install) of an HTTP 562 server carrying the OpenBSD OSREV distribution. 563 The installation program will try to fetch a list 564 of such servers; depending on your network settings, 565 this might fail. If the list could be fetched, it 566 will be displayed, and you can choose an entry from 567 the list (the first entries are expected to be the 568 closest mirrors to your location). 569 3) The directory holding the distribution sets. 570 571 Then refer to the section named "installation set selection" 572 below.-:})dnl 573dnl 574define({:-OpenBSDCDROMInstall-:}, 575{:- To install from CD-ROM: 576 When installing from a CD-ROM, you will be asked which 577 device holds the distribution sets. This will typically 578 be "cd0". If there is more than one partition on the 579 CD-ROM, you will be asked which partition the distribution 580 is to be loaded from. This is normally partition "a". 581 582 You will also have to provide the relative path to the 583 directory on the CD-ROM which holds the distribution, for 584 the MACHINE this is "OSREV/MACHINE". 585 586 Then refer to the section named "installation set selection" 587 below.-:})dnl 588dnl 589define({:-OpenBSDNFSInstall-:}, 590{:- To install from an NFS mounted directory: 591 When installing from an NFS-mounted directory, you must 592 have completed network configuration above, and also 593 set up the exported file system on the NFS server in 594 advance. 595 596 First you must identify the IP address of the NFS server 597 to load the distribution from, and the file system the 598 server expects you to mount. 599 600 The install program will also ask whether or not TCP 601 should be used for transport (the default is UDP). Note 602 that TCP only works with newer NFS servers. 603 604 You will also have to provide the relative path to the 605 directory on the file system where the distribution sets 606 are located. Note that this path should not be prefixed 607 with a "/". 608 609 Then refer to the section named "installation set selection" 610 below.-:})dnl 611dnl 612dnl OpenBSDDISKInstall({:-<additional disk> or-:}, <-- $1 613dnl {:-only -:}, <-- $2 614dnl {:- or <other fs name>-:}) <-- $3 615dnl 616dnl Note the spacing used above. It is crucial to keep words from running 617dnl together in the actual document. 618dnl 619dnl Arg 1 is optional. 620dnl Choices for args 2 & 3: 621dnl - OpenBSDDISKInstall(,{:-only -:}) 622dnl (only have 1 fs possible, ffs) 623dnl - OpenBSDDISKInstall(,,{:-or <insert some other filesystem name>-:}) 624dnl (have another fs possible for reading during disk install) 625dnl 626dnl see $1, $2, and $3 below for further usage information. 627dnl 628define({:-OpenBSDDISKInstall-:}, 629{:- To install from a local disk partition: 630 When installing from a local disk partition, you will 631 first have to identify which disk holds the distribution 632 sets. 633 This is normally $1"sdN", where N is a number. 634 Next you will have to identify the partition within that disk 635 that holds the distribution; this is a single letter between 636 "a" and "p". 637 638 You will also have to identify the type of file system 639 residing in the partition identified. Currently, you can 640 $2{:--:}install from partitions that have been formatted as the 641 Berkeley fast file system (ffs)$3. 642 643 You will also have to provide the relative path to the 644 directory on the file system where the distribution sets 645 are located. Note that this path should not be prefixed 646 with a "/". 647 648dnl Then refer to the section named "installation set selection" 649dnl below. 650 Then refer to the next section.-:})dnl 651dnl 652define({:-OpenBSDCommonInstall-:}, 653{:- Installation set selection: 654 A list of available distribution sets found on the 655 given location will be listed. 656 657 You may individually select distribution sets to install 658 by entering their names or wildcards (e.g. "*.tgz" or 659 "base*|comp*"), or you may enter "all" to select all the 660 sets (which is what most users will want to do). 661 You may also enter "abort" to deselect everything and 662 restart the selection from scratch, or unselect sets 663 by entering their name prefixed with "-" (e.g. "-x*"). 664 665 It is also possible to enter an arbitrary filename and 666 have it treated as a file set. 667 668 When you are done selecting distribution sets, enter 669 "done". The files will begin to extract.-:})dnl 670dnl 671dnl Description of the end of the installation procedure. 672dnl 673define({:-OpenBSDInstallWrapup-:}, 674{:- After the files have been extracted, you will be given the choice 675 to select a new location from which to install distribution sets. 676 If there have been errors extracting the sets from the previous 677 location, or if some sets have been missing, this allows you to 678 select a better source. 679 680 Also, if the installation program complains that the distribution 681 sets you have been using do not match their recorded checksums, you 682 might want to check your installation source (although this can 683 happen between releases, if a snapshot is being updated on a mirror 684 server with newer files while you are installing). 685 686ifelse(MDTZ,,dnl 687{:- The last thing you'll need to configure is the time zone your system 688 will be using. For this to work properly, it is expected that you 689 have installed at least the "base{:--:}OSrev" and "bsd" distribution sets. 690-:},dnl 691{:- The last thing you might need to configure, if you did not get 692 the chance to earlier, is the time zone your system will be using. 693 For this work properly, it is expected that you have installed at 694 least the "base{:--:}OSrev" and "bsd" distribution sets. 695-:})dnl 696dnl install.sh finish_up() 697 698 The installation program will then proceed to save the system 699 configuration, create all the device nodes needed by the installed 700 system, and will install bootblocks on the root disk. 701ifelse(MDSMP,,,{:- 702 On multiprocessor systems, if the bsd.mp kernel has been installed, 703 it will be renamed to "bsd", which is the default kernel the boot 704 blocks look for. The single processor kernel, "bsd", will be 705 available as "bsd.sp". 706-:}) 707 Finally, you will be asked whether you would like to install 708 non-free firmware files (which can't be tightly integrated to 709 the OpenBSD system) on first boot, by invoking fw_update(8) on 710 the next boot.-:})dnl 711dnl 712define({:-OpenBSDCongratulations-:},{:- 713Congratulations, you have successfully installed OpenBSD OSREV. When you 714reboot into OpenBSD, you should log in as "root" at the login prompt. 715You should create yourself an account, if you skipped this step during 716installation, and protect it and the "root" account with good passwords. 717 718The install program leaves root an initial mail message. We recommend 719you read it, as it contains answers to basic questions you might have 720about OpenBSD, such as configuring your system, installing packages, 721getting more information about OpenBSD, sending in your dmesg output 722and more. To do this, run 723 724 mail 725 726and then just enter "more 1" to get the first message. You quit mail by 727entering "q". 728 729Some of the files in the OpenBSD OSREV distribution might need to be 730tailored for your site. We recommend you run: 731 732 man afterboot 733 734which will tell you about a bunch of the files needing to be reviewed. 735If you are unfamiliar with UN*X-like system administration, it's 736recommended that you buy a book that discusses it.-:})dnl 737dnl 738dnl 739dnl ========== Autoinstall instructions 740dnl (usually used by arch/install) 741dnl 742dnl OpenBSDUnattendedInstallation()dnl 743define({:-OpenBSDUnattendedInstallation-:}, 744{:-dnl 745Preparing an unattended installation of OpenBSD: 746------------------------------------------------ 747 748If "(A)utoinstall" is chosen at the install prompt or if the 749installation system detects that it booted from the network, and 750isn't interrupted within 5 seconds, it attempts a fully-automatic 751installation. 752 753The installer autoconfigures a DHCP IPv4 address on the network interface the 754system booted from, or in case of multiple interfaces it will ask which one 755to use. Upon success, it retrieves a response file via HTTP. If that 756fails, the installer asks for the response file location, which can be 757either a URL or a local path, and retrieves the response file from 758there. 759 760The "next-server" DHCP option specifies the hostname part of the URL, 761as in "http://<next-server>/install.conf". The "filename" DHCP 762parameter specifies the installer mode, e.g. "auto_install". On 763architectures where this parameter is used for netbooting, create 764a symbolic link named "auto_install" pointing to the boot program. 765 766The response file contains lines with key/value pairs separated by 767an equals sign "=", where the key is a non-ambiguous part (up to the 768question mark) of the installer question, consisting of whitespace 769separated words. The value is what would have been entered at the 770interactive prompt. Empty lines and lines beginning with a "#" 771character are ignored. The installer uses default answers in case 772of missing answers. 773 774Here is a response file example that uses a hashed password (see 775encrypt(1) for more details) for root and a public ssh key for the 776user that is created during the installation. 777 778 System hostname = openbsd 779 Password for root = ${:--:}2a${:--:}14${:--:}Z4xRMg8vDpgYH...GVot3ySoj8yby 780 Setup a user = puffy 781 Password for user = ************* 782 Public ssh key for user = ssh-ed25519 AAAAC3NzaC1...g3Aqre puffy@ai 783 What timezone are you in = Europe/Stockholm 784 Location of sets = http 785 HTTP Server = ftp.eu.openbsd.org 786 787The "System hostname" key above matches the following full question 788asked during an interactive installation: 789 790 System hostname? (short form, e.g. 'foo') 791 792While the installation is in progress the installer writes all output 793to the file /ai.log, which is available as mail on the freshly 794installed system after the initial reboot. If the installation is 795successful the system will reboot automatically; otherwise, you will 796be dropped back into the shell where you can look at the /ai.log file 797or try again. 798 799dnl XXX: do we want this? 800dnl A more complete example of a response file is distributed with the 801dnl OpenBSD installation sets for amd64, which is recommended to use as a 802dnl starting point and reference for writing your own. 803-:})dnl 804dnl 805dnl 806dnl ========== Upgrade instructions 807dnl (usually used by arch/upgrade) 808dnl 809dnl OpenBSDUpgrade({:-<list of available boot methods>-:})dnl 810dnl Parameter is optional. 811define({:-OpenBSDUpgrade-:}, 812{:-Warning! Upgrades to OpenBSD OSREV are currently only supported from the 813immediately previous release. The upgrade process will also work with older 814releases, but might not execute some migration tasks that would be necessary 815for a proper upgrade. 816 817The best solution, whenever possible, is to backup your data and reinstall 818from scratch. As a minimum, if the toolchain (the "comp" set) was installed, 819you should remove all files within /usr/{:-include-:} before attempting to 820upgrade. 821 822To upgrade OpenBSD OSREV from a previous version, start with the general 823instructions in the section "Installing OpenBSD". 824 825Boot from $1. 826When prompted, select the (U)pgrade option rather than the (I)nstall 827option at the prompt in the install process. 828 829You will be presented with a welcome message, and depending on how you are 830connected to the system, you will be asked to set the terminal type or to 831choose a keyboard layout. 832 833The upgrade script will ask you for the existing root partition, and 834will use the existing filesystems defined in /etc/fstab to install the 835new system in. It will also use your existing network parameters. 836 837From then, the upgrade procedure is very close to the installation 838procedure described earlier in this document. 839 840However, it is strongly advised that you unpack the etc{:--:}.tgz and the 841xetc{:--:}.tgz files found in /var/sysmerge in a temporary 842directory and merge changes by hand, or with the help of the sysmerge(8) 843helper script, since all components of your system may not function 844correctly until your files in "/etc" are updated.-:})dnl 845dnl 846dnl 847dnl ========== Installation media preparation 848dnl (usually used by arch/xfer) 849dnl 850dnl Generic preparation introduction, after the list of various sources. 851dnl Use the short version unless there are too many methods, in this case 852dnl the long versions adds a ``don't panic!'' notice. 853define({:-OpenBSDXferShortPrelude-:}, 854{:-The steps necessary to prepare the distribution sets for installation 855depend on which method of installation you choose. Some methods 856require a bit of setup first that is explained below. 857 858The installation allows installing OpenBSD directly from HTTP mirror 859sites over the internet, however you must consider the speed and 860reliability of your internet connection for this option. It may save 861much time and frustration to download the distribution sets to a local 862server or disk and perform the installation from there, rather than 863directly from the internet.-:})dnl 864define({:-OpenBSDXferPrelude-:}, 865{:-OpenBSDXferShortPrelude 866 867The variety of options listed may seem confusing, but situations vary 868widely in terms of what peripherals and what sort of network arrangements 869a user has, the intent is to provide some way that will be practical.-:})dnl 870dnl 871dnl Various floppy generation instructions. 872dnl 873define({:-OpenBSDXferCDROM-:}, 874{:-Creating a bootable CD-ROM: 875 876 First you need to get access to the OpenBSD bootable CD-ROM (ISO) 877 images. They can be found on one of the OpenBSD mirror servers. Two 878 files are available, install{:--:}OSrev.iso which contains all of 879 the sets needed for installation, and a smaller cd{:--:}OSrev.iso 880 which contains just the installer, for a network install. 881 882 Windows users should be able to do this by right clicking on the 883 install{:--:}OSrev.iso file and clicking burn to CD. 884 885 OpenBSD users should be able to do this with the cdio command. 886 "cdio tao install{:--:}OSrev.iso" 887 888 Users of other operating systems should consult the 889 appropriate documentation.-:})dnl 890dnl 891define({:-OpenBSDXferFloppyFromDOS-:}, 892{:-Creating a bootable floppy disk using Windows: 893 894 First you need to get access to the OpenBSD bootable floppy 895 images. If you can access the distribution from the CD-ROM under 896 DOS, you will find the bootable disks in the OSREV/MACHINE 897 directory. Otherwise, you will have to download them from one of 898 the OpenBSD mirror sites, using an FTP client or a web browser. 899 In either case, take care to do "binary" transfers, since 900 these are images files and any DOS cr/lf translations or Control-z 901 EOF interpretations will result in corrupted transfers. 902 903 You will also need to go to the "tools" directory and grab a copy of 904 the ntrw.exe utility. Run it with the correct arguments like this 905 "ntrw <image> <drive>:" 906 907 Note that, when installing, the boot floppy can be write-protected 908 (i.e. read-only).-:})dnl 909dnl 910define({:-OpenBSDXferFloppyFromUNIX-:}, 911{:-Creating a bootable floppy disk using a Un*x-like system: 912 913 First, you will need to obtain a local copy of the bootable filesystem 914 image as described above. You should use the signify(1) and sha256(1) 915 commands to verify the integrity of the images with the SHA256.sig file 916 on the mirror site. 917 918 Next, use the dd(1) utility to copy the file to the floppy drive. 919 The command would likely be, under OpenBSD: 920 dd if=floppy{:--:}OSrev.img of=/dev/rfd0c bs=36b 921 922 If you are using another operating system, you may have to adapt 923 this to conform to local naming conventions for the floppy and 924 options suitable for copying to a "raw" floppy image. The key 925 issue is that the device name used for the floppy *must* be one 926 that refers to the correct block device, not a partition or 927 compatibility mode, and the copy command needs to be compatible 928 with the requirement that writes to a raw device must be in 929 multiples of 512-byte blocks. The variations are endless and 930 beyond the scope of this document. 931 932 If you're doing this on the system you intend to boot the floppy on, 933 copying the floppy back to a file and doing a compare or checksum 934 is a good way to verify that the floppy is readable and free of 935 read/write errors. 936 937 Note that, when installing, the boot floppy can be write-protected 938 (i.e. read-only).-:})dnl 939dnl 940define({:-OpenBSDXferUSBFromUNIX-:}, 941{:-Creating a bootable USB key using a Un*x-like system: 942 943 Some older systems may not be able to boot from USB keys or require 944 changing boot priority. Check your BIOS settings if you run into 945 problems. 946 947 First, you will need to obtain a local copy of the bootable filesystem 948 image miniroot{:--:}OSrev.img or install{:--:}OSrev.img as described above. 949 You should use the signify(1) and sha256(1) commands to verify 950 the integrity of the images with the SHA256.sig file on the mirror site. 951 952 Next, use the dd(1) utility to copy the file to the USB storage device. 953 The command would likely be, under OpenBSD: 954 dd if=miniroot{:--:}OSrev.img of=/dev/rsdNc bs=1m 955 956 where N is the device number. You can find the correct device number 957 by checking dmesg(8) when inserting the media. 958 959 If you are using another operating system, you may have to adapt 960 this to conform to local naming conventions for the USB key and 961 options suitable for copying to a "raw" disk image. The key 962 issue is that the device name used for the USB key *must* be one 963 that refers to the correct block device, not a partition or 964 compatibility mode, and the copy command needs to be compatible 965 with the requirement that writes to a raw device must be in 966 multiples of 512-byte blocks. The variations are endless and 967 beyond the scope of this document. 968 969 If you're doing this on the system you intend to boot the USB key on, 970 copying the image back to a file and doing a compare or checksum 971 is a good way to verify that the USB key is readable and free of 972 read/write errors.-:})dnl 973dnl 974dnl OpenBSDXferNFS [(noupgrade)] 975define({:-OpenBSDXferNFS-:}, 976{:-To install OpenBSD using a remote partition, mounted via 977NFS, you must do the following: 978 979 NOTE: This method of installation is recommended only for 980 those already familiar with using BSD network 981 configuration and management commands. If you aren't, 982 this documentation should help, but is not intended to 983 be all-encompassing. 984 985 Place the OpenBSD distribution sets you wish to install 986 into a directory on an NFS server, and make that directory 987 mountable by the machine on which you are installing or 988 upgrading OpenBSD. This will probably require modifying 989 the /etc/exports file of the NFS server and resetting 990 its mount daemon (mountd). (Both of these actions will 991 probably require superuser privileges on the server.) 992 993 You need to know the numeric IP address of the NFS 994 server, and, if the server is not on a network directly 995 connected to the machine on which you're installing or 996 upgrading OpenBSD, you need to know the numeric IP address 997 of the router closest to the OpenBSD machine. Finally, 998 you need to know the numeric IP address of the OpenBSD 999 machine itself. 1000 1001 Once the NFS server is set up properly and you have the 1002 information mentioned above, you can proceed to the next 1003 step in the installation ifelse(X$1,X,{:-or upgrade -:})process.ifelse(X$1,X,,{:- If you're 1004 installing OpenBSD from scratch, go to the section on 1005 preparing your hard disk, below. If you're upgrading an 1006 existing installation, go directly to the section on 1007 upgrading.-:})-:})dnl 1008dnl 1009define({:-OpenBSDXferFFS-:}, 1010{:-If you are upgrading OpenBSD, you also have the option of installing 1011OpenBSD by putting the new distribution sets somewhere in your 1012existing file system, and using them from there. To do that, do 1013the following: 1014 1015 Place the distribution sets you wish to upgrade somewhere 1016 in your current file system tree. At a bare minimum, you 1017 must upgrade the "base" binary distribution, and so must 1018 put the "base{:--:}OSrev" set somewhere in your file system. It 1019 is recommended that you upgrade the other sets, as well.-:})dnl 1020dnl 1021define({:-OpenBSDInstNFS-:}, 1022{:-Now you must populate the "/dev" directory for your client. If the server 1023does not run OpenBSD you might save the MAKEDEV output: 1024 1025 eo=echo ksh MAKEDEV all > all.sh 1026 1027and then tailor it for your server operating system before running it. Note 1028that MAKEDEV is written specifically for ksh, and may not work on any other 1029Bourne shell. 1030 1031There will be error messages about unknown users and groups. These errors are 1032inconsequential for the purpose of installing OpenBSD. However, you may 1033want to correct them if you plan to use the diskless setup regularly. In that 1034case, you may re-run MAKEDEV on your OpenBSD machine once it has booted.-:})dnl 1035