OpenBSD New User FAQ Version .2 by Jonathan Katz: jkatz@openbsd.org These are a few of the questions that seem to be asked every so-often on the mailing list. This is very early in the making for such a document, so if it doesn't contain what you are looking for, please ask and feel free to contribute. This document DOES NOT cover the installation process. Sections: 1) Non-standard hardware OR "I can't get my hardware to work." 2) Virtual Consoles 3) How to compile a kernel 4) Getting source code 5) Rebuilding my system 6) Ethernet quirks 7) Problems loading X11 (XFree86) 8) Finding other software (ports). 9) Where do I get my OpenBSD 2.1 CD? 10) disklabel and fdisk 11) Miscellany (HELP!) ------------------------------------------------------- 1) My foobar 1230 SCSI adapter (or other peripheral) has a non-standard irq and doesn't work with the GENERIC or INSTALL kernels! Yes it does. With a little tinkering and patience, anything can be accomplished. At the OpenBSD boot prompt type "-c". IT should look something like this: [OpenBSD boot Rev. 1.0a] boot>> -c You will eventually get a 'UKC>' prompt. Here you can type "list" and list all the devices that are compiled into this kernel. Once you find the name of the device you'd like to change, type "change devicename". UKC will guide you through the different attributes of the device that can be configured. Once you are finished adding the necessary configurations, you'll be back at the UKC> prompt. At the prompt type "quit" and your machine will continue to boot, with the updated info. 2) How do I get virtual consoles? To start, virtual consoles are only supported on the i386 port. The default GENERIC kernel (the one you normally get after doing an install) has support for virtual consoles compiled in. If you are using an older GENERIC kernel, or a different kernel, support for "vt0" (the kernel device that controls virtual consoles) may not be included. If you are using the 2.1 release GENERIC kernel, you will have virtual consoles enabled. 2.1) Now that I know I have virtual consoles, how do I use them? Unlike Linux, you need to hit cntrl+alt+fn to swap from console to console. By default (with the files in /dev from your install, and a newly compiled kernel with vt0 support) you have four (F1 through F4) virtual consoles. If you make more ttyC devices in /dev (cd /dev; MAKEDEV ttyC4; MAKEDEV ttyC5; MAKEDEV ttyC6; MAKEDEV ttyC7;) and edit /etc/ttys so that all the tty's are on, you will have a standard 8 virtual consoles. 3) How do I compile a kernel? Kernels can be compiled in under 9 steps (WOW!) 1) get the source code VIA FTP, CTM, or CVS (skip to CVS section if need be) 2) cd /usr/src/sys/arch/(your_machine_type)/conf NOTE: (your_machine_type) will vary with what kind of processor you use. On my VAX 3400, it would be: /usr/src/sys/arch/vax/conf On my P5/100 it would be: /usr/src/sys/arch/i386/conf On my Sparc IPC it would be: /usr/src/sys/arch/sparc/conf 3) edit a config file to your liking and save it as a new name. (vi GENERIC; :w NEW_KERNEL_NAME :q) Things to keep in mind: Make your kernel name snazzy (you don't HAVE to do that). Most people keep their kernel names in caps (general convention). 4) type "config NEW_KERNEL_NAME" If all goes according to plan it will tell you to "don't forget to make depend!" If config chokes on your file, look at what it says and play with your configuration until you get it right. 5) cd /usr/src/sys/arch/(your_machine_type)/compile/NEW_KERNEL_NAME NOTE: config makes that DIRECTORY "NEW_KERNEL_NAME" all by itself. 6) make depend ; make 7) su (if not root already); cp /bsd /bsd.old; cp bsd /bsd 8) shutdown/reboot your system. 9) Enjoy your custom kernel :-) 4) How do I get source code? OpenBSD source code is obtained VIA CVS, FTP or CTM. If you've ftp'd the distribution of OpenBSD, it should be pretty simple for you to figure out how to FTP the source. CTM is covered in its own document on the WWW server. As for CVS, here is your crash course. I've found that getting code VIA CVS is fast, easy, and means you get newer/better/bugfixed code. NOTE: For example purposes I'm using anoncvs.openbsd.org which is a few miles of fiber away from me in the United States. You may want to pick a nearer cvs site for you to use (especially if you are downloading the tree, as downloading OpenBSD's powerful crypto from the States to sites in Europe breaks various laws). See the OpenBSD WWW sites for a cvs mirror close to home. If these instructions are not working for you, please skip to the section that talks about the "pserver" that has been set-up in order to aleviate the headache of a proxy/firewall that may be causing you some greif. INITIAL USE: cd /usr setenv CVSROOT anoncvs@anoncvs.openbsd.org:/cvs cvs -z 9 -q get -PA src UPDATE USE: cd /usr/src setenv CVSROOT anoncvs@anoncvs.openbsd.org:/cvs cvs -z 9 -q up -PAd "pserver" WORK-AROUND: cd /usr setenv CVSROOT :pserver:anoncvs@anoncvs5.usa.openbsd.org:/cvs cvs login cvs -z9 -q get src .. [From: Todd Miller... millert@openbsd.org] A quick explanation of the flags: "-z 9" turns on compression-- the same as "gzip -9" "-q" makes it quiet, as CVS can generate a lot of output "-d" will create and update new directories if your tree does not have them "-P" prunes out old directories "-A" resets sticky tags 5) How do I rebuild my system? Depending on what version system you have and what version source you have, it can be as easy as four steps, and as legnthy as 22. If you have a 2.1 CD (or downloaded 2.1) and are using "-current" sources, you should be able to recompile in 4 steps. In order to get 2.1 (and later) versions to compile on a 2.0 based system, things get a little tricky. 5.1) "The Four Steps" (as opposed to the Four Questions) If you want to be risky, you can just try doing a "make -k build" in /usr/src-- the four steps below follow a prudent guideline for making a new system. 1) cd /usr/src/share/mk; make install 2) mkdir /usr/obj; cd /usr/src; make obj 3) make -k build && make install 4) make cleandir A quick explanation: 1) "fixes" Makefiles and make (if broken, which somestimes happens) 2) makes the directory for objects, then makes the objects 3) builds the entire system. "-k" is a flag to make that tries to have make progress if there are any errors. "make build" also builds the dependencies. "make install" makes SURE it gets installed-- "make build" is supposed to do the installing. 4) this cleans up the source tree (deletes out extra binaries, etc) 5.2) The long version. These are very detailed instructions given to misc@openbsd.org from Marco Hyman. If you aren't too paranoid, you can actually skip some of the stuff in there, at your own risk. Please read through carefully. If you aren't careful, you can actually hose your system up :( From marc@dumbcat.codewright.com Sun May 4 17:57:34 1997 Date: Sat, 03 May 1997 12:10:35 -0700 From: Marco S Hyman To: tech@openbsd.org, misc@openbsd.org Subject: From 2.0 to current in 22 steps Someone (Theo?) recently said that updating from a 2.0 to current was a bitch. That sounded enough like a challenge that I thought I'd try it -- and document what I had to do at the same time. Hope this is helpful to others. Given: o System running 2.0 code o -current source tree mounted as /usr/src. My -current source lives on a different host, so it happens to be NFS mounted. This code was current as of 1 May. o An empty /usr/obj on the local disk. Variables: * $arch=i386, the architecture I'm generating the code for * $config=TRAVEL, my configuration file. This is a copy of ALL with everything I don't use commented out and a few minor changes. Travel is a Toshiba laptop and I wanted the PCMCIA modem to be com1 and the PCMCIA ethernet card to be either ed0 or ep0, depending upon which flavor or card I happen to be using. Ok, here are the steps. Disclaimer mode: - Some may not be necessary. - There may be necessary steps that I missed and just luckely have not run into problems yet. - The order that I did things may be wrong. - Etc. [ FAQ assembler's note: This mailing was hearlded by some as a masterpiece rivaling the Magna Carta :) ] [ 1] cd /usr/src/share/mk && make install use the new make for everything [ 2] cd /usr/src/includes && make includes use the new included for everything [ 3] cd /usr/src/bin/pdksh && make && make install && make clean This is installed as /bin/sh which is needed for the next step. The 2.0 /bin/sh does not work with making the object links. The `make clean' step is to get the $arch specific objects out of the source directory. [ 4] cd /usr/src && make obj make the obj links so that code is generated on the local disk, not the NFS mounted source disk. (Note: the kernel is still generated in /sys/arch/$arch/compile/$config). [ 5] cd /usr/src/usr.bin/mktemp && make && make install mktemp is required to generate a kernel [ 6] cd /usr/src/usr.sbin/config && make depend && make && make install The latest config MUST be used to generate the new kernel. If you don't use this config you won't get past the "make depend" step of kernel generation. [ 7] cd /sys/arch/$arch/conf edit your $config file if necessary. [ 8] config $config generate required files to build updated kernel. [ 9] cd ../compile/$config && make clean && make depend && make Don't forget the make clean. It may not be necessary, but doesn't hurt in any case. The new config may have even warned you to do this. [10] mv /bsd /bsd- && mv bsd / Get ready... [11] reboot Reboot your box and watch the console to see what's going on. In my case all went well. Xdm started and gave me my console login. I ssh'd from another host, su'd, and then re-mounted the current source on /usr/src. uname -a says: OpenBSD travel.codewright.com 2.1 TRAVEL#0 i386 [12] cd /usr/src && make cleandir We start with this step of the build process because the /usr/src/share/mk and the include files were installed above. [13] cd /usr/src/usr.bin/compile_et && make depend && make && make install this tool is required to build the libraries. [14] cd /usr/src/usr.bin/mk_cmds && make depend && make && make install this tool is required to build the libraries [15] cd /usr/src/lib && make depend && make && make install Go and have dinner then see a movie. This should be done just about the time you get back to the console. At least that's how long it takes on my old pentium portable. [16] cd /usr/src/gnu/usr.bin/ld && make depend && make && make install needed for the gnu libraries (libg++ will fail) [17] cd /usr/src/gnu/lib && make depend && make && make install [18] cd /usr/src/kerberosIV && make build [19] cd /usr/src/gnu/usr.bin/texinfo && \ make -f Makefile.bsd-wrapper && \ make -f Makefile.bsd-wrapper install The updated makeinfo is required by gcc which is generated before makeinfo when doing a standard `make' [20] cd /usr/src && make depend && make && make install [21] reboot See that everything comes up. If your source lives on a remote machine (like mine does), mount it on /usr/src. [22] cd /usr/src && make build This step is optional. I like to use the generated system to regenerate the full system just to ensure that all is OK. Probably best to start this before you go to bed. It might be done by the time you wake up. As I type this I've completed steps 1-21. Step 22 is in progress. I'll mail out an update if I run into any problems. Again, I hope this is helpful to others. // marc There you have it! 6) Why can't I use my old linux ifconfig commands and flags? Linux's implementations of "ifconfig" and "route" are not standard. OpenBSD's versions are normal. To get my ne2000 clone working, I type: corinne# ifconfig ed2 205.212.82.80 up corinne# route add default 205.212.82.1 That should work to get ANY ethernet interface working, as long as you specify the correct IP numbers and interface. 6.1) Whenever I do anything to the network I get a "device timeout" error!?! This is because you have an incorrect hardware or irq address assigned to your ethernet interface. To fix this, reboot the machine with the "-c" flag and change the attributes for your ethernet interface. See the general instructions in item 1 of this FAQ on how to change how the kernel talks to your hardware. 6.2) Hey, my IP Aliasing breaks after trying to add a third host! Aliasing one additional host usually isn't a big deal. When a user tries to alias a third or fourth host, sometimes things break. Adding "netmask 0xffffffff" to the end of your "ifconfig" for adding the aliased host solves the problem. i.e.: sparcy# ifconfig le0 alias 123.45.67.89 netmask 0xffffffff 7) Why won't XFree86 load on my (insert really cool/expensive, you know-it-will-work-because-you-checked-it-on-the-compatability-list at xfree86.org) graphics card? Some of the X servers require direct access to "/dev/mem" (raw memory) in order to work. By default, the OpenBSD kernel does not allow for this. There are two solutions: A) recompile a kernel with "option insecure" in your configuration file. B) Use the "apature" Loadable Kernel Module (lkm) found in the X11 distribution. 8) Where's pine (or other GNU/semi-free utility)? All about ports (as cribbed from www.openbsd.org/ports.html) OpenBSD is a fairly complete system of its own, but there still is a lot of software that one might want see added to their own system. However, one has to draw the line on what to include and leave out, as well as having to follow licensing and export restrictions laws. Because of these problems, some software cannot be shipped with the system. We wanted to find a way for users to easily get software we don't provide and started to look around. We didn't have to look far because a sibling project, FreeBSD, has an excellent mechanism for exactly this purpose called "The Ports Collection". After thinking about it for a while we decided to try and use their collection as is, feeding back necessary patches that make the ports work on OpenBSD as well as FreeBSD. The ports idea is to have, for each piece of software, a Makefile that describes where to download it from, how to alter the sources (if needed) and how to build and install it. Furthermore some patches will have to be kept in the "port" as well as some administration files for the package registry utilities. Normally this information is kept in an hierarchy under /usr/ports (this is configurable, and can be changed). The entire ports tree can be found at ftp://ftp.freebsd.org/pub/FreeBSD/FreeBSD-current/ports.tar.gz Note that this isn't a file on their server, rather it archives their directories on-the-fly. The entire collection is almost 3.1M tarred and gzip'd and will probably be twice that when uncompressed. The ports tree is also on the 2.1 CD. Let's say you managed to get a ports tree sitting under /usr/ports, then you should be able to something like this: mitnick% su mitnick# cd /usr/ports/archivers/unzip mitnick# make mitnick# make install mitnick# exit Easy, huh? 9) Where do I get my OpenBSD 2.1 CD? To preface, because OpenBSD contains powerful crypto, CDs are being distributed from Canda, Sweden, and Argentina. CDs cost $30 US plus shipping ($3-$8 US, generally). The CDs are a two CD set, complete with binaries for the Alpha, i386, Sparc, Amiga, Arc, Mac (68k), Pmax, and Motorola 68k VME systems, source code, X11R6.3, XFree86 3.3 (binaries and sources). In addition, The CDs are designed to be bootable on multiple architectures. http://www.openbsd.org/orders.html will take you through the credit card on-line odering system. To order VIA phone, call +1 (403) 605-8166 between 8AM and 5PM North American Mountain Standard Time. Please have your American Express, Master Card or Visa ready. 10) disklabel and fdisk disklabel and fdisk are different in OpenBSD than what most users are used to in different oprating systems. Both disklabel and fdisk are coverend in-depth in various install documents as well as their respective man pages. This portion of the FAQ is here only to explain the philosophy of the situation. In OpenBSD, disklabel is the core program used to modify and view a system's hard disk. disklabel is used to establish the disk's partitions as well as write the OpenBSD disklabel to disk. disklabel is also used to display which partitions are which. By running disklabel with an argument like "wd0" (think "disklabel wd0") the output will show not only what partitions of the disk are used by OpenBSD, but also what partitions ca be used to access DOS partitions. Unlike Linux, DOS, or FreeBSD, OpenBSD's fdisk is not full-screen/interactive. fdisk is used to manipulate partitions other than OpenBSD partitions as wel as the MBR on various hard disks. If you are sharing a disk between DOS and OpenBSD, you can change which partition is active with fdisk. fdisk can also be used to display the same partition information as disklabel, although the format of the output is different. 11) XXYYZZ (system something) is broken! The OpenBSD source tree is always evolving. The 2.1 release is wonderful and stable; however since the release snapshots will be made with many bugfixes every so often. Make sure you are running the latest code before giving up. See the OpenBSD ftp mirrors (as listed on the OpenBSD www sites) as well as the CVS section on how to obtain the source. ALSO, watch the misc@openbsd.org and announce@openbsd.org mailing lists for vital information. As another resource with your problems, check the OpenBSD mailing list archive, where it is quite possible that your question or concern has already been addressed. PS: always "man (utility)" and "apropos (problem)" because the answer you are looking for can lurk in the documentation. 970615 jkatz@openbsd.org