Our newuser FAQ might as well be in the source tree, right?

1 files changed, 437 insertions, 0 deletions

diff --git a/distrib/notes/newuser_faq b/distrib/notes/newuser_faq
new file mode 100644
index 00000000000..a60d972bdfb
--- /dev/null
+++ b/distrib/notes/newuser_faq
@@ -0,0 +1,437 @@
+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
+<type any password, it will return ok...work>
+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 <marc@dumbcat.codewright.com>
+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