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