init.app/getty.app/login.app/gemsh.app

authors: Ulrich Kaiser (kaiser.do@noell.de)
         Holger Kleinschmidt (holgerkl@cs.tu-berlin.de)

state: freeware, no warranty, use at your own risk


introduction:
-------------
init.app allows you to login under GEM e.g. as a non-root user. The
environment variable $HOME will be set according to current user.


installation:
-------------
Experts may skip the following lines:

{\begin novice}
At first you  should  build	 an	 UNIX-alike	 directory	structure. For this
purpose just copy the directories

bin
usr
etc
var
home

from the GEM-init archive into the root	directory of a drive of	your choice
(best a minixfs partition), e.g. drive m:.

IF THESE DIRECTORIES AND ITS FILES ALREADY	EXIST, YOU WILL	HAVE TO	FILL UP
THE	MISSING	DIRECTORIES	AND	FILES STEP BY STEP WITHOUT OVERWRITING EXISTING
FILES.

Next thing to do is	to let	these  directories appear in drive u:. This	may
be done by inserting the following lines into MiNT.Cnf:

# m: is assumed to be a Minixfs partition
echo setting symbolic links...
sln m:\bin u:\bin
sln m:\usr u:\usr
sln m:\home u:\home
sln m:\etc u:\etc
sln m:\var u:\var

and reboot the system.
{\end novice}

Copy your favorite desktop (e.g. Thing:-) including	its	corresponding files
to /usr/sbin. In /usr/sbin then	you	have  to set a link	to "desktop.app" or
you	 have  to  make	  a	  copy	 of	  your	desktop	 called	 "desktop.app".
Alternatively, edit	gemsh.rsc and write	 the  complete path	to your	desktop
into the free  string  "DESKTOP"  (default	is u:\usr\sbin\desktop.app). Or
edit the file ~/.desktop.

You	should have	installed  correct	versions  of  the files	/etc/passwd	and
/etc/group.

For	the	sake of	security  install  init.app	 with  the	s-bit set (chmod +s
init.app) if GEM has not been started by the root. Then:

a) SingleAES:
   install init.app as GEM auto-start program
   (#Z 01 U:\USR\SBIN\INIT.APP@ in NEWDESK.INF)

   comment the entries for INIT= and GEM= of MINT.CNF
   run MINTNP.PRG, NOT MINT.PRG from your AUTO folder

b) AES 4.x:
   invoke init.app with the following line in GEM.CNF:
   shell u:\usr\sbin\init.app

   DO NOT INSTALL IT AS GEM AUTO START!

   pay attention to the line with GEM= which contains the complete path to
   AES 4.x; comment the line with INIT=

c) Geneva 5.x:
   invoke init.app with the following line in GEM.CNF:
   shell u:\usr\sbin\init.app

   DO NOT INSTALL IT AS GEM AUTO START!

   pay attention to the line with INIT= which contains the complete path to
   Geneva 5.x; comment the line with GEM=

d) N.AES:
   install init.app with the following line in N_AES.CNF as shell:  
   shell u:\usr\sbin\init.app

   play attention to the line with GEM= which contains the complete path to
   the N.AES binary; comment the line with INIT=

e) XaAES:
   start init.app with the following line in XAAES.CNF:
   run u:\usr\sbin\init.app

f) oAESis:
   install init.app with the following line in OAESIS.CNF as shell:
   shell u:\usr\sbin\init.app

g) MagiC: invoke init.app as shell with the following line in MAGX.INF:
   #_SHL u:\usr\sbin\init.app
   where the line with #_SHL has to be written before the line with #_CTR
   (pontrol panel entries)
   (but you need either a version of MagiC for MiNT or a desktop which
   handles MagiC+MiNT or a version of MiNT for MagiC or a version of 
   MagiC supporting all important MiNT functions or a suitable patch
   program...)

h) MiNA, anything else: who knows it?

For	experts: of	course,	you	 may  write	 something	into the INIT= entry of
MINT.CNF. But to get to	GEM	and	 so	 to	GEM-init, the INIT=	program	must be
terminated or you have to run GEM right	from there (by means of	special	GEM
starters).

init.app absolutely	depends	on	the	 file /etc/ttytab.gem. ttytab.gem tells
init.app, which	 program  is  responsible  for	which  interface. It should
contain at least one entry for the console:

console "/usr/etc/getty.app console" vt52 on secure

That means that	/usr/etc/getty.app is responsible  for the console,	for	the
other  interfaces  like	 /dev/ttya	is	/usr/etc/getty	(part  of  the KGMD
distribution).	Later,	the	 parameter	vt52  should  appear  in  $TERM, if
everything went	ok.	You	may	 use  something	 else  than	 vt52, e.g.	tt52 or
vt100. MiniWin seems to evaluate tw, tw52 and st52.

If not	yet	 existing  you	should	create	two	 empty	files /etc/utmp	and
/var/adm/wtmp or else the UNIX commands who, ac and last will not work.

The file /etc/hostname should contain the hostname of your computer.

Furthermore, the directory /bin should contain an UNIX shell named sh.

Hint: if you want to run programs  as overlays of the desktop (under single
AES) there must	be a copy or  link	of	the	desktop	with its original name.
For	example, the  file	name  of  Ease	4.00  must	be	written	as EASE.PRG
(capital letters).

You	may	omit the renaming of the desktop into desktop.app or the editing of
gemsh.rsc. In this case,  an  alert	 will  appear  and	you	may	select your
desktop using the file selector (" open... ^O ").


related files:
--------------
init.app, getty.app, login.app und gemsh.app will try to open the following
files:
/etc/passwd
/etc/group
/etc/hostname
/etc/utmp
/etc/shells                     future use
/etc/desktops                   future use
/etc/rc.gem   
/etc/motd                       future use
/etc/ttytab.gem
/etc/init.{snd,au,svx,avr,iff,hsn,wav,voc,sam}
/var/adm/wtmp
/var/adm/lastlog                future use
/var/spool/mail/*               future use?
/dev/console
/dev/tty?                       acc. to /etc/ttytab.gem
/pipe/log                       future use
/bin/sh
/bin/terminal.app               only under AES 4.x
/bin/messages                   only under AES 4.x
/usr/etc/getty                  acc. to /etc/ttytab.gem
/usr/share/locale/{$LANG}/*.rsc future use
{$PATH}/showaudio
~/.gemrc
~/.gemshrc                      future use
~/.desktop        
~/.accrc 
~/login.{snd,au,svx,avr,iff,hsn,wav,voc,sam}
~/logout.{snd,au,svx,avr,iff,hsn,wav,voc,sam}

Only to your information: getty tries to open the following files:
/etc/gettytab
/usr/bin/login
/bin/sh


department of rights:
---------------------
The following access rights are recommended:

file            owner group mode       comment
------------------------------------------------------------------
/etc            root  root  drwxrwxr-x
/bin            root  root  drwxrwxr-x
   init.app     root  root  srwx--x--- (srwx--x--x N.AES or XaAES)
   init.rsc     root  root   rw-rw---- ( rw-rw-r-- N.AES or XaAES)
/etc/passwd     root  root   rw-r-----
/etc/group      root  root   rw-r-----
/etc/hostname   root  root   rw-r--r--
/etc/utmp       root  root   rw-rw-rw-
/etc/ttytab.gem root  root   rw-rw-r--
/var/adm/wtmp   root  root   rw-rw-rw-
/etc/rc.gem     root  root   rw-rw----
/etc/desktops   root  root   rw-rw-r--
/etc/shells     root  root   rw-rw-r--
  getty.app     root  root   rwx--x--x
  getty.rsc     root  root   rw-rw-r--
  login.app     root  root   rwx--x--x
  login.rsc     root  root   rw-rw-r--
  gemsh.app     root  root   rwx--x--x
  gemsh.rsc     root  root   rw-rw-r--
desktop.app     root  root   rwx--x--x
desktop.*       root  root   rw-rw-r--
~               user  user  drwx------
~/.gemrc        user  user   rw-------
~/$SCRAPDIR     user  user  drwx------


working:
--------
init.app runs getty.app	 and  login.app	 in	 an	 endless  loop.	login reads
/etc/passwd	and	compares the dialog	input  with	the	entries	in /etc/passwd.
After a	successfull	login $HOME	will be	set	and	gemsh.app will be launched.
gemsh first	starts the login shell,	then the desktop. After	the	termination
of the desktop the next	 user  may	login.	The	 whole procedure shown in a
graphic way:

    root: init
           |
    root: spawn(WAIT,/bin/sh,/etc/rc.gem)
           |
   ------->|
  |        |
  | root: fork()----------
  |        |              |
  | root: wait()  root: exec(/usr/etc/getty.app) (->/etc/ttytab.gem)
  |        |              |
  | root: wait()  root: fork()----------
  |        |              |             |
  | root: wait()          ê     root: exec(/usr/bin/login.app)
  |        |                            |
  | root: wait()                root: setsid()
  |        |                            |
  | root: wait()                root: setgid()
  |        |                            |
  | root: wait()                root: setuid()
  |        |                            |
  | root: wait()                user: fork()----------
  |        |                            |             |
  | root: wait()                        ê     user: exec(/bin/gemsh.app)                  
  |        |                                          |
  | root: wait()                              user: spawn(WAIT,login shell,~/.gemrc) *)
  |        |                                          |
  | root: wait()                              user: spawn(WAIT,desktop)
  |        |                                          |
  |        |<-----------------------------------------
  |        |
   --------

*) under AES 4.x the following things will be done:
   
   user: shel_write(/bin/loginsh)
             |             |
             |     user: fork()----------
             |             |             |
             |             ê     user: exec(login shell)
             |                                   |
   user: shel_write(desktop)                     |
             |         |                         |


environmentals:
---------------
$LINES    set it in MiNT.Cnf
$COLUMNS  set it in MiNT.Cnf
$ROWS     use it alternatively to $LINES
$HOME     will be set by init.app corresponding with /etc/passwd
$PATH     currently it will be set by init.app to fixed values, at first in
          UNIX-, then GEMDOS style:
          /bin:/usr/bin:/usr/ucb:.
          C:\;.;u:\usr\sbin
          the AES's PATH environment is not touched
$SHELL    will be set by init.app containing the path to the login shell
$TOSRUN   set it in GEM.Cnf/N_AES.Cnf, currently not used
$UNIXMODE set it in MiNT.Cnf, it has an influence to unix2dos()
$CLIPBRD  set by gemsh.app, contains the user's clipboard
$SCRAPDIR s. $CLIPBRD
$THINGDIR currently, gemsh.app sets it to $HOME
$HOSTNAME if this variable exists, /etc/hostname will not be evaluated
$LOGNAME  contains the login name
$FULLNAME contains the full user name (pw_gecos)
$TZ       set it in MiNT.Cnf
$TERM     will be set by init.app according to /etc/ttytab.gem
          caution: MinWin will set $TERM to tw52

KGMD login also sets a variable named $USER to the same value as $LOGNAME.

Caution: if	you	 boot  some	 program  to  set  the	AES's environment (like
SETENV.PRG), it	may	happen	that  the  environment	set	in MiNT.Cnf	will be
ignored. Better	set	 all  necessary	 environment  variables	 in	MiNT.Cnf or
GEM.Cnf/N_AES.Cnf.


tips & tricks:
--------------
As under single	AES	init.app has to	 be	 installed	as a GEM auto start	but
not	under a	multi AES and as  you  alternately	want to	boot single	AES	and
multi AES, you are recommended to  replace	by	means of a file	monitor	the
string NEWDESK.INF (existing twice) within GEM.SYS by e.g. NEWDESK.CNF.

It does	not	deal with init.app or gemsh.app, but nevertheless: if you run a
GEM	program	from a minixfs and	it	cannot find	its	resource file, the most
cases renaming the filename	of	the	 resource  file	to capital letters will
help. This is an error of the corresponding GEM program.

As well: if	you	like to	run	MiNTnp and MiNTNet and miscellaneous .XFS under
SingleAES, you will	 have  to  boot	 NoHog.Acc.	 SingleAES	loves to run in
supervisor mode	and	so MiNT	cannot	do its context switches. NoHog switches
into user mode again and again.

If somebody	does not like  the	moving	corner	of the login dialog, he	may
hide it by means of his RCS, but never remove it.

Currently, you are not recommended to  launch  any programs	by the run call
of GEM.CNF or N_AES.CNF. First,	 these	programs  will always run with root
rigths - as	long as	AES	has	been started by	the	root. Second, these	program
will not survive the next logout.
