-- Inittab Modifications for Minix v1.5.10 --

This volume contains the necessary changes to implement Lew Pitcher's
modifications to Minix v1.5.10 for inittab support.

The volume consists of:
 
etc/			Mirror of /etc directory
	inittab		- sample inittab
	rc.sysinit	- sample system initialization script
	rc0		- sample system shutdown script

usr/man/		Mirror of /usr/man directory
	proc1.1		- manual page for proc1 replacment for bootstrap init
	init.1		- manual page for /etc/init and /bin/telinit
	inittab.3	- manual page for /etc/inittab file

usr/include/		Mirror of /usr/include directory
	utmp.h.diff	- diff for utmp.h to create a new header file
			  for utmp processing

usr/src/lib/posix/	Mirror of /usr/src/lib/posix directory
	getut.c		- library code to support utmp processing (SVID)

usr/src/tools/		Mirror of /usr/src/tools directory
	Makefile	- New tools Makefile, to support alternate boot
	proc1.c		- replaces init.c in boot. Will load init from /etc

usr/src/commands/	Mirror of /usr/src/commands directory
	init.c		- init.c code to implement inittab processing
	login.c.diff	- diff for login.c with changes for new utmp use
	getty.c.diff	- diff for getty.c with changes for new utmp use
	users.c		- users.c recoded for getut.c 
	who.c.diff	- diff for who.c with changes for new utmp use
	last.c		- diff for last.c with changes for new utmp use


How to install:

	a) Back up everything
	b) cpdir -m each installation subdirectory to it's corresponding
	   system directory
	c) apply utmp.h.diff to /usr/include/utmp.h
	d) make getut.s, and add it to the libc.a library
	e) apply diffs to /usr/src/commands
	f) make init, login, getty, users, who, and last
	f) move login, and sh to the /bin directory, move init to /etc
	g) using the provided Makefile, make itab to compile proc1.c and
	   create a new boot diskette.
	h) edit /etc/inittab for your installation. The minimum inittab
	   would be:
		tty0::respawn:/bin/login </dev/tty0 >/dev/tty0 2>&1
	i) Double check everything... Any binary necessary for your inittab
	   startup (prior to mounts, etc) should be located in the root fs.
	   Also, init can reside on /bin or /etc, but proc1 will expect to
	   find login on /bin.
	j) Back up everything again.  These changes have not disabled the
	   the original system, but backing out will be a bit of a pain.
	k) shutdown, and reboot from the new boot diskette.


	That's it.

	From here on, you can edit /etc/inittab to include your site
	specific startups and shutdowns.


Principals of Operation

	init
		init can be invoked by either the boot (as process id 1), or
		by a user process. Init performs differently for each type
		of invocation and this behaviour difference is documented
		here.

		Init invoked by a user process
			When invoked in this manner, this occurrance of init
			will not have a process id of 1. This is crucial, as
			the startup logic in init uses the process id to
			determine the subsequent processing path. In this
			case, init will validate the single 1-character
			argument given to the command line, and perform an
			update action on the /etc/utmp file.

			The 1-character argument can be one of following:
			0 | 1 | 2 | 3 | 4 | 5 | 6 | s | S | q | Q  
			If 'q' or 'Q' are encountered, a kill(SIGHUP) is sent
			to process id 1, and the user process terminates.
			If one of the other valid characters are detected,
			the RUN_LVL record in the /etc/utmp file is updated
			to reflect the given argument, and a kill(SIGHUP) is
			sent to process id 1. Any other argument returns an
			error, as does failure to update the utmp file
			(permissions, etc.).

		Init invoked by the boot
			When invoked in this manner, this occurrance of init
			*will* have a process id of 1. In this case, the
			processing characteristic of the 'root' process will
			be performed.

			This invocation of init takes no arguments, and this
			occurrance of init will never terminate. This init
			acts as the mother of all further user processes,
			starting and stopping them as indicated by the value
			of the current run state and the contents of the
			/etc/inittab file.

			The "run state" is a single character indicator used
			by Init to select entries from the /etc/inittab file.
			Normally recorded on the /etc/utmp file in a RUN_LVL
			record, this indicator can be set to one of the
			following values:
			    '0' | '1' | '2' | '3' | '4' | '5' | '6' | 's'.

			Periodically, init will retrieve the run level from
			/etc/utmp, and follow a transition to the indicated
			state. By convention, the 8 run states each have
			different purposes.

			Run Level '0'	is used to place the system
			"Shutdown"	in a state from which it can
					be safely shut down.
			Run Level '1'	is used to place the system
			"Maintenance"	in a state in which only 1
					local login is enabled, all
					daemons are disabled, and
					only the root file system is
					mounted.
			Run Level 's'	is used to place the system in a
			"Single User"	single user mode in which only 1
					local login is enabled, but daemons
					are left running, and filesystems
					are left mounted.
			Run Level '2'	is used to place the system in a
			"Multi-User"	multi-user mode in which all local
					logins are enabled, daemons are
					run, and filesystems mounted.
			Run Level '3'	is used to place the system in a
			"Networked"	multi-user mode in which both
					local and remote logins are
					enabled, daemons are run, and
					file systems are mounted.
			Run Level '4'	user defined
			Run Level '5'	user defined
			Run Level '6'	user defined

			When init is invoked as process id 1, it performs the
			following processing steps:
				a) establish initial environment
				b) parse /etc/inittab for all 'sysinit' and
			 	  'initdefault' entries, save the initial
				   run level for further processing
				c) record BOOT_TIME in utmp and wtmp
				d) parse /etc/init for all entries matching
				   the current run level
				e) record RUN_LVL in utmp and wtmp
				f) establish the SIGHUP signal handler
				g) parse /etc/init for all 'respawn' entries
				   matching the current run level (in case
				   one has terminated already)
				h) wait on termination of a child process
				i) go back to (g) to process death of child
				   process as it may be a respawnable child

			If SIGHUP is intercepted during step (h), the run
			level is refreshed from the /etc/utmp RUN_LVL record,
			and processing is continued at step (d). This permits
			user invocations of init, or kill to cause the run
			level to refresh.

			When init launches a process, it forks off a child,
			which parses the inittab 'process' field, and
			establishes the required stdin, stdout, and stderr
			file descriptors. Init does not perform any other
			parsing; to do so would require a significant portion
			of the logic from sh, which was not feasable in this
			design.

			/etc/utmp and /usr/adm/wtmp are updated when a
			process is launched, and again when a process
			terminates. The sequence of records in wtmp differs
			slightly from the Minix 1.5.10 implementation, and
			thus has required changes in several utilities. login
			and getty have been altered to accomodate this
			change, and who, users, and last have been changed
			to accomodate both this change, and the inclusion of
			RUN_LVL records.

	proc1
		The init binary must be resident in one of the libraries so
		that authorized users can invoke it to change the system
		state. As it is also used as the first user process (PID 1),
		the boot must be able to execute it as well. Also, in a
		development system, it is likely that init may be altered by
		the sysop to suit the needs of the local system. All these
		factors taken together indicate the need for a copy of init
		outside of the boot binary, and that init must remain in sync
 		with the init imbedded in the boot.

		To simplify matters somewhat (and reduce the size of the boot
		binary as well), I have seperated init out of the boot, and
		replaced it with a simple program which 'exec's init from a
		known directory. This permits me to maintain only 1 copy of
		the init binary, while still permitting its use by both the
		boot and the user.

		Proc1's only purpose is to exec init. It attempts to execute
		/etc/init, and failing that /bin/init. If both of these fail,
		it tries to exec /bin/login so that the sysop can rebuild
		init on either /etc or /bin. This logic is looped, so that
		once /bin/login completes, proc1 retries /etc/init,
		/bin/init, and /bin/login again. The loop terminates once
		one of /etc/init or /bin/init are successfully launched.

		If none of the above named binaries are found, proc1 hangs,
		and a reboot must be done against a valid root filesystem.
		It would be a good idea to keep a 'standalone' root file 
		system on diskette, so that if proc1 fails in this manner,
		you can reboot with a filesystem that has /bin/login and
		repair the failure.


Caveats.

	I make no warrantees for this package. It runs without error on my
	Minix 1.5.10 system, but you're system may be different.

	Read all the material before installing; make backups of everything
	(both this stuff, and your own system); take a close look at the 
	source code changes before compiling (I haven't documented every
	little thing); compile to a work library and test from there; only
	migrate tested code; you get the point. Please don't sue me, as I
	have no money. 

	

	Lew Pitcher
	4 Nobel Place,
	Brampton, Ontario.
	Canada, L6S-4X6
