1dnl 2dnl $OpenBSD: m4.common,v 1.121 2016/07/28 17:19:24 zhuk 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. 107 ifelse(MDSO,,{:-It excludes everything described below.-:},{:-It includes shared library support, and excludes everything 108 described below.-:})showsize($1,$2)-:})dnl 109dnl 110dnl 111dnl OpenBSDcomp( compressed size, uncompressed size ) 112dnl Describes compXX.tgz. 113dnl 114define({:-OpenBSDcomp-:}, 115{:- comp{:--:}OSrev The OpenBSD/MACHINE Compiler tools. All of the tools relating 116 to C, C++ and Objective-C are supported. This set includes 117 the system {:-include-:} files (/usr/{:-include-:}), the linker, the 118 compiler tool chain, and the various system libraries{:--:}ifelse(MDSO,,.,{:- 119 (except the shared libraries, which are included as part of 120 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.fs 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.fs 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.fs 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 initialising, 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 ``rtsol'' 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 setup, 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 xdm 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 setup 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 with the users 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 setup 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 You may now be given the opportunity to configure the time zone 426 your system will be using (this depends on the installation 427 media you are using). 428 429 If the installation program skips this question, do not be 430 alarmed, the time zone will be configured at the end 431 of the installation. 432-:})dnl 433dnl install.sh ask whether to use DUIDs before the md_prep_disklabel loop 434 The installation program will now tell you which disks it can 435 install on, and ask you which it should use. 436 437 Reply with the name of your root disk.-:})dnl 438dnl install.sh md_prep_disklabel loop 439dnl 440dnl OpenBSDInstallMBRPart1 441dnl Describes MBR partitioning. So much to save four lines of text 442dnl duplicated 5 times. 443dnl 444define({:-OpenBSDInstallMBRPart1-:}, 445{:- Disks on OpenBSD/MACHINE are partitioned using either ``MBR'' 446 or ``GPT'' partitioning schemes. You will need to create one 447 disk partition in which the OpenBSD filesystems will be created. 448-:})dnl 449dnl 450dnl OpenBSDInstallMBRPart2(needs OpenBSD partition active) 451dnl Describes fdisk invocation 452dnl 453define({:-OpenBSDInstallMBRPart2-:}, 454dnl install.md md_prep_fdisk 455{:- The installation program will ask you if you want to use the 456 whole disk for OpenBSD. If you don't need to or don't intend 457 to share the disk with other operating systems, answer `w' 458 here to use ``MBR'' partitioning or 'g' to use ``GPT'' 459 partitioning. The installation program will then create a single 460 partition spanning the whole disk, dedicated to OpenBSD. 461 462 Otherwise, fdisk(8) will be invoked to let you to edit your 463 partitioning. The current artitions defined will be 464 displayed and you will be allowed to modify them, add new 465 partitions, and change which partition to boot from by default. 466 467ifelse(X$1,X,, 468{:- Note that you should make the OpenBSD partition the active 469 partition at least until the install has been completed. 470-:})dnl 471 After your OpenBSD partition has been created, dividing the 472 space into filesystems can follow. 473-:})dnl 474dnl 475dnl OpenBSDInstallPart5(mention about other OS partitions,mention about root 476dnl partition limitations) 477dnl Describes the disklabel operation 478dnl 479define({:-OpenBSDInstallPart5-:}, 480{:- The file system layout is stored in the OpenBSD disk label. Each 481 file system is stored in its own ``disk label partition'', which 482 is a subdivision of the OpenBSD disk partition you created. In 483 the text below ``partition'' refers to these subdivisions. 484 485 You will be shown a default layout with the recommended file 486 systems. This default layout is based on the disk size. 487 488 You will be given the choice of accepting the proposed layout, 489 editing it, or creating your own custom layout. These 490 last two choices will invoke the disklabel(8) interactive editor, 491 allowing you to create your desired layout. 492 493 Within the editor, you will see at least a 'c' partition of 494 fstype 'unused'. This represents the whole disk and cannot be 495 modified.$1 496 497 You must create partition 'a' as a native OpenBSD partition, i.e. 498 one with "4.2BSD" as the fstype, to hold the root file system.$2 499 500 In addition to partition 'a' you should create partition 'b' with 501 fstype "swap", and native OpenBSD partitions to hold separate file 502 systems such as /usr, /tmp, /var, and /home. 503 504 You will need to provide a mount point for all partitions you 505 {:-define-:}. Partitions without mount points, or not of the 506 4.2BSD fstype, will neither be formatted nor mounted during the 507 installation. 508 509 For quick help while in the interactive editor, enter '?'. The 510 `z' command (which deletes all partitions and starts with a 511 clean label), the `A' command (which performs the automatic 512 partition layout) and the `n' command (to change mount points) 513 are of particular interest. 514 515 Although the partitions position and size are written in exact 516 sector values, you do not need a calculator to create your 517 partitions! Human-friendly units can be specified by adding `k', 518 `m' or `g' after any numbers to have them converted to kilobytes, 519 megabytes or gigabytes. Or you may specify a percentage of the 520 disk size using `%' as the suffix. 521 522 Enter 'M' to view the entire manual page (see the info on the 523 ``-E'' flag). To exit the editor enter 'q'.-:})dnl 524dnl 525dnl OpenBSDInstallPart6(other installation sources) 526define({:-OpenBSDInstallPart6-:}, 527{:- After the layout has been saved, new filesystems will be 528 created on all partitions with mount points. 529 This will DESTROY ALL EXISTING DATA on those partitions. 530 531 After configuring your root disk, the installer will 532 return to the list of available disks to configure. 533 534 You can choose the other disks to use with OpenBSD in 535 any order, and will get to setup their layout similarly 536 to the root disk above. However, for non-root disks, 537 you will not be proposed a default partition layout. 538 539 When all your disks are configured, simply hit return 540 at the disk prompt. 541 542 After these preparatory steps have been completed, you will be 543 able to extract the distribution sets onto your system. There 544 are several install methods supported: 545 HTTP, $1or a local disk partition.-:})dnl 546dnl 547dnl Notes for various installation methods. 548dnl 549define({:-OpenBSDURLInstall-:}, 550{:- To install via HTTP: 551 To begin an HTTP install you will need the following 552 pieces of information: 553 1) Proxy server URL if you are using a URL-based HTTP 554 proxy (squid, CERN FTP, Apache 1.2 or higher). 555 You need to {:-define-:} a proxy if you are behind a 556 firewall that blocks outgoing HTTP connections 557 (assuming you have a proxy available to use). 558 2) The IP address (or hostname if you configured 559 DNS servers earlier in the install) of an HTTP 560 server carrying the OpenBSD OSREV distribution. 561 The installation program will try to fetch a list 562 of such servers; depending on your network settings, 563 this might fail. If the list could be fetched, it 564 will be displayed, and you can choose an entry from 565 the list (the first entries are expected to be the 566 closest mirrors to your location). 567 3) The directory holding the distribution sets. 568 569 Then refer to the section named "installation set selection" 570 below.-:})dnl 571dnl 572define({:-OpenBSDCDROMInstall-:}, 573{:- To install from CD-ROM: 574 When installing from a CD-ROM, you will be asked which 575 device holds the distribution sets. This will typically 576 be "cd0". If there is more than one partition on the 577 CD-ROM, you will be asked which partition the distribution 578 is to be loaded from. This is normally partition "a". 579 580 You will also have to provide the relative path to the 581 directory on the CD-ROM which holds the distribution, for 582 the MACHINE this is "OSREV/MACHINE". 583 584 Then refer to the section named "installation set selection" 585 below.-:})dnl 586dnl 587define({:-OpenBSDNFSInstall-:}, 588{:- To install from an NFS mounted directory: 589 When installing from an NFS-mounted directory, you must 590 have completed network configuration above, and also 591 set up the exported file system on the NFS server in 592 advance. 593 594 First you must identify the IP address of the NFS server 595 to load the distribution from, and the file system the 596 server expects you to mount. 597 598 The install program will also ask whether or not TCP 599 should be used for transport (the default is UDP). Note 600 that TCP only works with newer NFS servers. 601 602 You will also have to provide the relative path to the 603 directory on the file system where the distribution sets 604 are located. Note that this path should not be prefixed 605 with a '/'. 606 607 Then refer to the section named "installation set selection" 608 below.-:})dnl 609dnl 610dnl OpenBSDDISKInstall({:-<additional disk> or-:}, <-- $1 611dnl {:-only -:}, <-- $2 612dnl {:- or <other fs name>-:}) <-- $3 613dnl 614dnl Note the spacing used above. It is crucial to keep words from running 615dnl together in the actual document. 616dnl 617dnl Arg 1 is optional. 618dnl Choices for args 2 & 3: 619dnl - OpenBSDDISKInstall(,{:-only -:}) 620dnl (only have 1 fs possible, ffs) 621dnl - OpenBSDDISKInstall(,,{:-or <insert some other filesystem name>-:}) 622dnl (have another fs possible for reading during disk install) 623dnl 624dnl see $1, $2, and $3 below for further usage information. 625dnl 626define({:-OpenBSDDISKInstall-:}, 627{:- To install from a local disk partition: 628 When installing from a local disk partition, you will 629 first have to identify which disk holds the distribution 630 sets. 631 This is normally $1"sdN", where N is a number. 632 Next you will have to identify the partition within that disk 633 that holds the distribution; this is a single letter between 634 'a' and 'p'. 635 636 You will also have to identify the type of file system 637 residing in the partition identified. Currently, you can 638 $2{:--:}install from partitions that have been formatted as the 639 Berkeley fast file system (ffs)$3. 640 641 You will also have to provide the relative path to the 642 directory on the file system where the distribution sets 643 are located. Note that this path should not be prefixed 644 with a '/'. 645 646dnl Then refer to the section named "installation set selection" 647dnl below. 648 Then refer to the next section.-:})dnl 649dnl 650define({:-OpenBSDCommonInstall-:}, 651{:- Installation set selection: 652 A list of available distribution sets found on the 653 given location will be listed. 654 655 You may individually select distribution sets to install, 656 by entering their name, or wildcards (e.g. `*.tgz' or 657 `base*|comp*', or `all' to select all the sets (which 658 is what most users will want to do). 659 You may also enter `abort' to deselect everything and 660 restart the selection from scratch, or unselect sets 661 by entering their name prefixed with `-' (e.g. `-x*'). 662 663 It is also possible to enter an arbitrary filename and 664 have it treated as a file set. 665 666 When you are done selecting distribution sets, enter 667 `done'. The files will begin to extract.-:})dnl 668dnl 669dnl Description of the end of the installation procedure. 670dnl 671define({:-OpenBSDInstallWrapup-:}, 672{:- After the files have been extracted, you will be given the choice 673 to select a new location from which to install distribution sets. 674 If there have been errors extracting the sets from the previous 675 location, or if some sets have been missing, this allows you to 676 select a better source. 677 678 Also, if the installation program complains that the distribution 679 sets you have been using do not match their recorded checksums, you 680 might want to check your installation source (although this can 681 happen between releases, if a snapshot is being updated on a mirror 682 server with newer files while you are installing). 683 684ifelse(MDTZ,,dnl 685{:- The last thing you'll need to configure is the time zone your system 686 will be using. For this to work properly, it is expected that you 687 have installed at least the "base{:--:}OSrev" and "bsd" distribution sets. 688-:},dnl 689{:- The last thing you might need to configure, if you did not get 690 the chance to earlier, is the time zone your system will be using. 691 For this work properly, it is expected that you have installed at 692 least the "base{:--:}OSrev" and "bsd" distribution sets. 693-:})dnl 694dnl install.sh finish_up() 695 696 The installation program will then proceed to save the system 697 configuration, create all the device nodes needed by the installed 698 system, and will install bootblocks on the root disk. 699ifelse(MDSMP,,,{:- 700 On multiprocessor systems, if the bsd.mp kernel has been installed, 701 it will be renamed to `bsd', which is the default kernel the boot 702 blocks look for. The single processor kernel, `bsd', will be 703 available as `bsd.sp'. 704-:}) 705 Finally, you will be asked whether you would like to install 706 non-free firmware files (which can't be tightly integrated to 707 the OpenBSD system) on first boot, by invoking fw_update(8) on 708 the next boot.-:})dnl 709dnl 710define({:-OpenBSDCongratulations-:},{:- 711Congratulations, you have successfully installed OpenBSD OSREV. When you 712reboot into OpenBSD, you should log in as "root" at the login prompt. 713You should create yourself an account and protect it and the "root" 714account with good passwords. 715 716The install program leaves root an initial mail message. We recommend 717you read it, as it contains answers to basic questions you might have 718about OpenBSD, such as configuring your system, installing packages, 719getting more information about OpenBSD, sending in your dmesg output 720and more. To do this, run 721 722 mail 723 724and then just enter "more 1" to get the first message. You quit mail by 725entering "q". 726 727Some of the files in the OpenBSD OSREV distribution might need to be 728tailored for your site. We recommend you run: 729 730 man afterboot 731 732which will tell you about a bunch of the files needing to be reviewed. 733If you are unfamiliar with UN*X-like system administration, it's 734recommended that you buy a book that discusses it.-:})dnl 735dnl 736dnl 737dnl ========== Autoinstall instructions 738dnl (usually used by arch/install) 739dnl 740dnl OpenBSDUnattendedInstallation()dnl 741define({:-OpenBSDUnattendedInstallation-:}, 742{:-dnl 743Preparing an unattended installation of OpenBSD: 744------------------------------------------------ 745 746If '(A)utoinstall' is choosen at the install prompt or if the 747installation system detects that it booted from the network, and 748isn't interrupted within 5 seconds, it attempts a fully-automatic 749installation. 750 751The installer runs dhclient(8) on the network interface the system 752booted from, or in case of multiple interfaces it will ask which one 753to use. Upon success it retrieves a response file via HTTP. If that 754fails, the installer asks for the response file location which can be 755either an url or a local path and retrieves the response file from 756there. 757 758The "next-server" DHCP option specifies the hostname part of the URL, 759as in "http://<next-server>/install.conf". The "filename" DHCP 760parameter specifies the installer mode, e.g. "auto_install". On 761architectures where this parameter is used for netbooting, create 762a symbolic link named "auto_install" pointing to the boot program. 763 764The response file contains lines with key/value pairs separated by 765an equals sign '=', where the key is a non-ambiguous part (up to the 766question mark) of the installer question, consisting of whitespace 767separated words. The value is what would have been entered at the 768interactive prompt. Empty lines and lines beginning with a '#' 769character are ignored. The installer uses default answers in case 770of missing answers. 771 772Here is a response file example that uses a hashed password (see 773encrypt(1) for more details) for root and a public ssh key for the 774user that is created during the installation. 775 776 System hostname = openbsd 777 Password for root = ${:--:}2a${:--:}14${:--:}Z4xRMg8vDpgYH...GVot3ySoj8yby 778 Setup a user = puffy 779 Password for user = ************* 780 Public ssh key for user = ssh-ed25519 AAAAC3NzaC1...g3Aqre puffy@ai 781 What timezone are you in = Europe/Stockholm 782 Location of sets = http 783 HTTP Server = ftp.eu.openbsd.org 784 785The "System hostname" key above matches the following full question 786asked during an interactive installation: 787 788 System hostname? (short form, e.g. 'foo') 789 790While the installation is in progress the installer writes all output 791to the file /ai.log, which is available as mail on the freshly 792installed system after the initial reboot. If the installation is 793successful the system will reboot automatically; otherwise, you will 794be dropped back into the shell where you can look at the /ai.log file 795or try again. 796 797dnl XXX: do we want this? 798dnl A more complete example of a response file is distributed with the 799dnl OpenBSD installation sets for amd64, which is recommended to use as a 800dnl starting point and reference for writing your own. 801-:})dnl 802dnl 803dnl 804dnl ========== Upgrade instructions 805dnl (usually used by arch/upgrade) 806dnl 807dnl OpenBSDUpgrade({:-<list of available boot methods>-:})dnl 808dnl Parameter is optional. 809define({:-OpenBSDUpgrade-:}, 810{:-Warning! Upgrades to OpenBSD OSREV are currently only supported from the 811immediately previous release. The upgrade process will also work with older 812releases, but might not execute some migration tasks that would be necessary 813for a proper upgrade. 814 815The best solution, whenever possible, is to backup your data and reinstall 816from scratch. As a minimum, if the toolchain (the ``comp'' set) was installed, 817you should remove all files within /usr/{:-include-:} before attempting to 818upgrade. 819 820To upgrade OpenBSD OSREV from a previous version, start with the general 821instructions in the section "Installing OpenBSD". 822 823Boot from $1. 824When prompted, select the (U)pgrade option rather than the (I)nstall 825option at the prompt in the install process. 826 827You will be presented with a welcome message, and depending on how you are 828connected to the system, you will be asked to set the terminal type or to 829choose a keyboard layout. 830 831The upgrade script will ask you for the existing root partition, and 832will use the existing filesystems defined in /etc/fstab to install the 833new system in. It will also use your existing network parameters. 834 835From then, the upgrade procedure is very close to the installation 836procedure described earlier in this document. 837 838However, it is strongly advised that you unpack the etc{:--:}.tgz and the 839xetc{:--:}.tgz files found in /var/sysmerge in a temporary 840directory and merge changes by hand, or with the help of the sysmerge(8) 841helper script, since all components of your system may not function 842correctly until your files in `/etc' are updated.-:})dnl 843dnl 844dnl 845dnl ========== Installation media preparation 846dnl (usually used by arch/xfer) 847dnl 848dnl Generic preparation introduction, after the list of various sources. 849dnl Use the short version unless there are too many methods, in this case 850dnl the long versions adds a ``don't panic!'' notice. 851define({:-OpenBSDXferShortPrelude-:}, 852{:-The steps necessary to prepare the distribution sets for installation 853depend on which method of installation you choose. Some methods 854require a bit of setup first that is explained below. 855 856The installation allows installing OpenBSD directly from HTTP mirror 857sites over the internet, however you must consider the speed and 858reliability of your internet connection for this option. It may save 859much time and frustration to download the distribution sets to a local 860server or disk and perform the installation from there, rather than 861directly from the internet.-:})dnl 862define({:-OpenBSDXferPrelude-:}, 863{:-OpenBSDXferShortPrelude 864 865The variety of options listed may seem confusing, but situations vary 866widely in terms of what peripherals and what sort of network arrangements 867a user has, the intent is to provide some way that will be practical.-:})dnl 868dnl 869dnl Various floppy generation instructions. 870dnl 871define({:-OpenBSDXferCDROM-:}, 872{:-Creating a bootable CD-ROM: 873 874 First you need to get access to the OpenBSD bootable CD-ROM (ISO) 875 images. They can be found on one of the OpenBSD mirror servers. Two 876 files are available, install{:--:}OSrev.iso which contains all of 877 the sets needed for installation, and a smaller cd{:--:}OSrev.iso 878 which contains just the installer, for a network install. 879 880 Windows 7 users should be able to do this by right clicking on the 881 install{:--:}OSrev.iso file and clicking burn to CD. 882 883 OpenBSD users should be able to do this with the cdio command. 884 "cdio tao install{:--:}OSrev.iso" 885 886 Users of other operating systems should consult the 887 appropriate documentation.-:})dnl 888dnl 889define({:-OpenBSDXferFloppyFromDOS-:}, 890{:-Creating a bootable floppy disk using Windows: 891 892 First you need to get access to the OpenBSD bootable floppy 893 images. If you can access the distribution from the CD-ROM under 894 DOS, you will find the bootable disks in the OSREV/MACHINE 895 directory. Otherwise, you will have to download them from one of 896 the OpenBSD mirror sites, using an FTP client or a web browser. 897 In either case, take care to do "binary" transfers, since 898 these are images files and any DOS cr/lf translations or Control-z 899 EOF interpretations will result in corrupted transfers. 900 901 You will also need to go to the "tools" directory and grab a copy of 902 the ntrw.exe utility. Run it with the correct arguments like this 903 "ntrw <image> <drive>:" 904 905 Note that, when installing, the boot floppy can be write-protected 906 (i.e. read-only).-:})dnl 907dnl 908define({:-OpenBSDXferFloppyFromUNIX-:}, 909{:-Creating a bootable floppy disk using a Un*x-like system: 910 911 First, you will need to obtain a local copy of the bootable filesystem 912 image as described above. You should use the signify(1) and sha256(1) 913 commands to verify the integrity of the images with the SHA256.sig file 914 on the mirror site. 915 916 Next, use the dd(1) utility to copy the file to the floppy drive. 917 The command would likely be, under OpenBSD: 918 dd if=floppy{:--:}OSrev.fs of=/dev/rfd0c bs=36b 919 920 If you are using another operating system, you may have to adapt 921 this to conform to local naming conventions for the floppy and 922 options suitable for copying to a "raw" floppy image. The key 923 issue is that the device name used for the floppy *must* be one 924 that refers to the correct block device, not a partition or 925 compatibility mode, and the copy command needs to be compatible 926 with the requirement that writes to a raw device must be in 927 multiples of 512-byte blocks. The variations are endless and 928 beyond the scope of this document. 929 930 If you're doing this on the system you intend to boot the floppy on, 931 copying the floppy back to a file and doing a compare or checksum 932 is a good way to verify that the floppy is readable and free of 933 read/write errors. 934 935 Note that, when installing, the boot floppy can be write-protected 936 (i.e. read-only).-:})dnl 937dnl 938define({:-OpenBSDXferUSBFromUNIX-:}, 939{:-Creating a bootable USB key using a Un*x-like system: 940 941 Some older systems may not be able to boot from USB keys or require 942 changing boot priority. Check your BIOS settings if you run into 943 problems. 944 945 First, you will need to obtain a local copy of the bootable filesystem 946 image miniroot{:--:}OSrev.fs or install{:--:}OSrev.fs as described above. 947 You should use the signify(1) and sha256(1) commands to verify 948 the integrity of the images with the SHA256.sig file on the mirror site. 949 950 Next, use the dd(1) utility to copy the file to the USB storage device. 951 The command would likely be, under OpenBSD: 952 dd if=miniroot{:--:}OSrev.fs of=/dev/rsdNc bs=1m 953 954 where N is the device number. You can find the correct device number 955 by checking dmesg(8) when inserting the media. 956 957 If you are using another operating system, you may have to adapt 958 this to conform to local naming conventions for the USB key and 959 options suitable for copying to a "raw" disk image. The key 960 issue is that the device name used for the USB key *must* be one 961 that refers to the correct block device, not a partition or 962 compatibility mode, and the copy command needs to be compatible 963 with the requirement that writes to a raw device must be in 964 multiples of 512-byte blocks. The variations are endless and 965 beyond the scope of this document. 966 967 If you're doing this on the system you intend to boot the USB key on, 968 copying the image back to a file and doing a compare or checksum 969 is a good way to verify that the USB key is readable and free of 970 read/write errors.-:})dnl 971dnl 972dnl OpenBSDXferNFS [(noupgrade)] 973define({:-OpenBSDXferNFS-:}, 974{:-To install OpenBSD using a remote partition, mounted via 975NFS, you must do the following: 976 977 NOTE: This method of installation is recommended only for 978 those already familiar with using BSD network 979 configuration and management commands. If you aren't, 980 this documentation should help, but is not intended to 981 be all-encompassing. 982 983 Place the OpenBSD distribution sets you wish to install 984 into a directory on an NFS server, and make that directory 985 mountable by the machine on which you are installing or 986 upgrading OpenBSD. This will probably require modifying 987 the /etc/exports file of the NFS server and resetting 988 its mount daemon (mountd). (Both of these actions will 989 probably require superuser privileges on the server.) 990 991 You need to know the numeric IP address of the NFS 992 server, and, if the server is not on a network directly 993 connected to the machine on which you're installing or 994 upgrading OpenBSD, you need to know the numeric IP address 995 of the router closest to the OpenBSD machine. Finally, 996 you need to know the numeric IP address of the OpenBSD 997 machine itself. 998 999 Once the NFS server is set up properly and you have the 1000 information mentioned above, you can proceed to the next 1001 step in the installation ifelse(X$1,X,{:-or upgrade -:})process.ifelse(X$1,X,,{:- If you're 1002 installing OpenBSD from scratch, go to the section on 1003 preparing your hard disk, below. If you're upgrading an 1004 existing installation, go directly to the section on 1005 upgrading.-:})-:})dnl 1006dnl 1007define({:-OpenBSDXferFFS-:}, 1008{:-If you are upgrading OpenBSD, you also have the option of installing 1009OpenBSD by putting the new distribution sets somewhere in your 1010existing file system, and using them from there. To do that, do 1011the following: 1012 1013 Place the distribution sets you wish to upgrade somewhere 1014 in your current file system tree. At a bare minimum, you 1015 must upgrade the "base" binary distribution, and so must 1016 put the "base{:--:}OSrev" set somewhere in your file system. It 1017 is recommended that you upgrade the other sets, as well.-:})dnl 1018dnl 1019define({:-OpenBSDInstNFS-:}, 1020{:-Now you must populate the `/dev' directory for your client. If the server 1021does not run OpenBSD you might save the MAKEDEV output: 1022 1023 eo=echo ksh MAKEDEV all > all.sh 1024 1025and then tailor it for your server operating system before running it. Note 1026that MAKEDEV is written specifically for ksh, and may not work on any other 1027Bourne shell. 1028 1029There will be error messages about unknown users and groups. These errors are 1030inconsequential for the purpose of installing OpenBSD. However, you may 1031want to correct them if you plan to use the diskless setup regularly. In that 1032case, you may re-run MAKEDEV on your OpenBSD machine once it has booted.-:})dnl 1033