This is the README for the consd package. 			      11Nov2009


Tools for virtual console management
------------------------------------

consd - virtual console management daemon
consinfod - virtual console information daemon

consd starts and kills gettys as needed. consinfod displays in the top
line of the screen which processes are currently running on the actual
console.


1. Installation
---------------

To compile, do a 'make', to install 'make install', to uninstall
'make uninstall'.

Please note that consinfod currently requires a small kernel patch to work
correctly. You must apply this patch by hand. To apply the patch, try this
(tested for a 2.0.33 to 2.0.36 kernel):

    ( cd /usr/src/linux 
      patch -p1 < wait_any_vt.diff )

This command assumes your full linux kernel sources can be found in
/usr/src/linux. Watch the output for errors. If a strange question comes up
('file to patch?') this is an error, too.

If it succeeded recompile and reinstall your kernel and reboot. If it didn't
succeed you cannot use consinfod with your kernel. The patch has been
created for Linux 2.0.33, but it should work with all 2.0.xx kernels.

The 2.1.xx kernels need another diff instead. There is a
wait_any_vt.diff-2.1.128 that was created for Linux 2.1.128. It should
also work for all newer kernels. For older 2.1.xx kernels I don't know.
Try one patch and see what happens. You may want to have a backup copy
of your kernel sources somewhere just in case the patched kernel does not
compile and you do not know how to make it work again :-)

The 2.4.x kernels need another diff instead. There is a
wait_any_vt.diff-2.4.0 that was created for Linux 2.4.0. It should
also work for all newer kernels.

    ( cd /usr/src/linux/drivers/char 
      patch -p0 < wait_any_vt.diff   )


The 2.6.x kernels need another diff instead. There is a
wait_any_vt_ioctl.diff-2.6.0 that was created for Linux 2.6.0. It should
also work for all kernels up to 2.6.19.

    ( cd /usr/src/linux/drivers/char 
      patch -p0 < wait_any_vt_ioctl.diff-2.6.0   )

With upcomming 2.6.7 kernels these patchfile was modified, but it schould
work with kernels 2.6.0 to 2.6.X

The next table is an overview on the patches

Kernel Version		tested		Patch
------------------------------------------------------------------
2.0.xx			o.K.		vt_2.xx patch
2.1.xx			o.K.		vt_2.1.128 patch
2.4.xx			o.K.		vt_2.4.0 patch
2.5.0 to 2.5.32		o.K.		vt_2.5.32 patch
2.5.33 to 2.5.xx	o.K.		vt_2.5.33.2 patch
2.6.0  to 2.6.19 	o.K.  		vt_ioctl_2.6.0 patch
2.6.20 to 2.6.22 	o.K.    	vt_ioctl_2.6.20 patch
2.6.23 to 2.6.25	o.K.		vt_ioctl_2.6.23 patch
2.6.26 to 2.6.30	o.K.		vt_ioctl_2.6.26 patch
2.6.31.5		o.K.		vt_ioctl_2.6.26 patch


All patches were classicly generated by 
	diff -u vt_ioctl.c.orig vt_ioctl.c > wait_vt_ioctl_X.XX.XX.patch

Please also verify that you have correct console devices in /dev. They are:

      * tty[0-63] (character device, major 4, minor 0-63)
      * vcs[0-63] (character device, major 7, minor 0-63)
      * vcsa[0-63] (character device, major 7, minor 128-191)

All of them should have these ownership and permissions (except for the
consoles that are currently in use - they are modified by login):

        crw--w--w-    root     tty

If you don't plan to use so much virtual consoles you can replace the 63
by the highest number you want. A common limit is 24. Some Linux
distributions provide inconsistent console devices (for example, tty[0-63]
but only vcs[0-24]. This cannot work! Either create the missing vcs devices
or remove the overhead of tty devices because they are not fully functional
without the corresponding vcs and vcsa devices. Otherwise you get annoying
warnings by consinfod until you correct this.

As the MAKEDEV script in my distribution sucks (or I suck - I simply didn't
manage to create the devices with it), I've written a small shell script
'mkconsdev' that creates the devices if they are missing. The script requires
an argument telling how much consoles to create. For example, if you want
to create all necessary devices for consoles 1 to 24, you enter:

       ./mkconsdev 24

The script does not remove or overwrite any devices. It also does not check
whether your setup is correct or self-consistent. As it's just safe to create
all possible 63 consoles, it's best to call it like this:

       ./mkconsdev 63


2. consd
--------

COMMAND LINE
  consd [-d] [-h] [-a] [-b] [-m max] [-p program args ...]

DESCRIPTION
  consd manages virtual consoles silently in the background. It starts and
  kills gettys there depending on how many gettys are just sitting around
  and waiting (and wasting ressources). Usually, consd ensures there's always
  one (and only one) getty waiting for someone to login. The virtual consoles
  with lower numbers are preferred.

  consd recognizes the following options:

  -d: Turn on debugging. Messages are printed to stderr. The daemon does not
      put itself into the background when debugging is enabled.

  -h: Print a short help.

  -a: Be more aggressive on unused consoles.

  -b: Bind to Spawn_Console key. Pressing that key causes to jump to a
      console with a waiting getty.

  -m: Set maximum number of virtual consoles. E.g. if you have only 10
      consoles configured, '-m 10' makes consd respect the limit. The default
      limit is 64, which is also the absolute maximum in the kernel.

  -p: Everything behind this is used as getty command line (%d is replaced
      with the tty number). There are no further options valid behind -p.

  If no getty command line is specified with the -p option, consd tries to
  guess the command line from /etc/inittab. If this fails, it tries some
  defaults compiled in. If these fail too, the program aborts with an error.

  To coexist in peace with init(8), gettys that were started by init are not
  killed. Virtual consoles used by init(8) are not touched. Thus, you may
  have more than one getty waiting because init wants it so.

  When reducing your number of gettys in inittab(5), please do not remove all
  gettys from inittab(5), init(8) does not like this at all. It is said that
  there should always be at least one getty in inittab(5).

SIGNALS
  Sending a SIGHUP to consd causes it to teleport you to a waiting getty.

KNOWN BUGS
  Command line guessing for gettys might lead to wrong results. You won't
  see a getty started by consd in that case. If this happens (you can find
  it out by turning on debugging) specify a getty command line with the -p
  option.

  In rare cases the consoles cannot be disallocated. Usually consd prints
  a warning on such consoles stating that the console is closed.

  In extremely rare cases there might be a dead login prompt left behind on
  the screen. This usually fools the users. Switch to a different console
  and login there. The dead console can be removed with deallocvt(1).

FILES
  /var/run/consd.pid - pid of running daemon

SEE ALSO
  agetty(8), getty_ps(8), or the documentation of whatever getty you prefer,
  inittab(5), gettydefs(5), deallocvt(1), consinfod(8)

TROUBLESHOOTING
  This is a list of known problems and their solutions. These are not consd
  bugs :)

  * On the additional consoles root cannot log in, only users can.

    Check /etc/securettys or /etc/login.defs for a list of consoles where
    root is allowed to log in. It depends on your distribution.

  * On the additional consoles applications mess up the screen.

    This may be caused by wrong terminal emulation e.g. wrong terminal type
    in the TERM environment variable. Usually, getty is expected to set the
    environment. Depending on the getty you are using you may have to set up
    additional configuration files (some gettys use /etc/gettydefs). Watch
    through all files /etc/*tty* and check the settings :)

  * I never see an additional console. I'm just stuck with those from init,
    and when they are all in use, no further one comes up.

    There's very likely a problem with the getty command line. Kill consd
    and run it with debugging enabled. If this turns out to be the problem,
    specify a getty command line with the -p option.

  * Where are the virtual consoles > 12 ?

    The virtual consoles 13-24 are on ALTGR-F1 to ALTGR-F12. On keyboards
    that don't have ALTGR try Right-ALT. If you still can't find them take
    a look at your keytable (usually in /usr/lib/kbd/keytables/*) for the
    'Console_%d' entries (replace %d with the number). If you don't load
    a keytable (perhaps because you have a US keyboard layout) you might
    want to setup your own table (there's a default us.map in the keytables
    directory). As I found, consoles higher than 24 are usually not defined.
    If you really need so much consoles, map them to some unused keys (e.g.
    ALT-<numeric keypad>, ALTGR-<numeric keypad>, CTRL-<numeric keypad>
    which should be enough for the missing 39 consoles...)

    Well, I've just found that you can cycle through your virtual consoles
    with ALT-ArrowLeft and ALT-ArrowRight. It's printed in the comments in
    the sources of the Linux keyborad driver...

    You can still change to any existing console with the chvt command
    (chvt <number>). But you need one console to type it in :)

  * What is the Spawn_Console key ?

    ALT-ArrowUp. It's not configured in the most keymaps, so you might want
    to add a line

           alt keycode 103 = Spawn_Console

    to your keymap file. Pressing that key can send a signal to a process.
    This is indeed what the -b switch does: consd then gets the signal from
    the Spawn_Console key and teleports you to a waiting getty.

  * I can't switch to the higher consoles from X.

    This is a X keyboard configuration question. :) But, as a simple
    solution, just change to one of the first consoles (e.g. with
    CTRL-ALT-F1) and then switch to the console you want. (Eh. If you
    really manage to get the higher consoles work from X let me know the
    trick please :)

  * After closing X the console remains dead.

    This is intended in order to let X always start on the same console.
    If you don't like this feature, use the -a switch - it makes consd
    more aggressive on reusing unused consoles.

  * I'm getting confused by so many consoles... can't find my programs...
    don't know where I am... uh-hu...

    Well, obviously the user has run out of ressources :) :) :)
    Now there's a solution available (consinfod). See below.


3. consinfod
------------

COMMAND LINE
  consinfod [-d] [-c] [-b] [-u] [-h] [-a attr] [-t time]

DESCRIPTION
  consinfod displays which processes are currently running on the actual
  virtual console. It just prints a line on top of the screen when virtual
  consoles are switched. consinfod currently requires a small kernel patch
  to allow the VT_WAITACTIVE 0 ioctl.

  consinfod recognizes the following options:

  -d: Turn on debugging. Messages are printed to stderr. The daemon does not
      put itself into the background when debugging is enabled.

  -h: Print a short help.

  -c: Show the full command line of the running processes (if available).
      Without this, only the process name is displayed.

  -b: Bind to the Spawn_Console key. Pressing that key displays the info
      text on the current console.

  -u: Show name of user who is logged in at the console.

  -f: Show only that process that is currently running in the foreground of
      the virtual terminal. If this switch is left out, all processes running
      on the virtual terminal are listed.

  -a: Set the screen attributes for the info text. Default is 31 which means
      white text on blue background. See console(4) and vcs(4) for more
      information.

  -t: Set the time (in seconds) after that the info text is removed from the
      screen again. Default is 1 second.

SIGNALS
  Sending a SIGHUP to consinfod causes it to display the info text on the
  current virtual terminal.

KNOWN BUGS
  In rare cases the top line of the console is not restored correctly after
  removing the info text. This typically affects applications that scroll
  the screen in reverse direction or otherwise change the top line while the
  info text is visible. The longer the time given with the -t switch the more
  likely this problem occurs.

FILES
  /var/run/consinfod.pid - pid of running daemon

SEE ALSO
  consd(8), console(4), vcs(4)

TROUBLESHOOTING
  This is a list of known problems and their solutions. These are not bugs
  in consinfod :)

  * When starting consinfod I receive a message like this:
    "consinfod: warning: you don't have /dev/vcs54 though /dev/tty54 exists."

    Your /dev directory is misconfigured. Each tty needs a vcs and a vcsa
    device. They are not only important for consinfod, but also for example
    for a mouse program (gpm, selection). Create the missing devices or
    remove the tty devices you never want (uhh... be careful not to remove
    the wrong ones). See under 'Installation' for a script that creates the
    missing devices.

  * It always exits with this error:
    "ioctl VT_WAITACTIVE 0 failed (maybe your kernel isn't patched) BLAH..."

    The message tells it all. consinfod requires a small kernel patch. It
    is included in file wait_any_vt.diff. See under 'Installation' how to
    apply it.

  * When working on a remote host, consinfod just displays "telnet".

    Well, consinfod cannot know which programs you have started on the remote
    machine.

  * The -f switch does not display what I expect.

    Okay, I must admit that documentation is a bit inaccurate here. The
    process displayed is that one with its PID equal to its TPGID. This is
    usually that process that you have started from the shell and that is now
    running in the foreground of the shell. If the process has created
    further subprocesses these are ignored. For example, if you have entered
    'make' and in fact it calls gcc and this again calls cpp (and so on)
    then the process 'make' is displayed.
  
  * The distribution uses an udev system for device management.

    This can be forced down by running the mkconsdev every system startup
    for example in the rc.local file. This is not the nice way, but it 
    works.

