Multics Technical Bulletin                                MTB-694
SSU_ SC, IOX MC, Logging Admin Mode

To:       Distribution

From:     Benson I. Margulies

Date:     11/12/84

Subject:  SSU_ System Control and IOX_ Message Coordinator


     The  B2 requirements  require us  to implement operator
     login,  to  improve  the  security  of  the  admin mode
     password, and  to audit operator traffic  in admin mode
     as  best  we  can.   These changes  proved  most easily
     implementable in  the context of  converting the system
     control (initializer) command  environment to ssu_, the
     message  coordinator terminal  management to  iox_, and
     all answering service logs to new (mtb666) style system
     logs.   This also  allows us to  fix a  large number of
     bugs,  and  generally improve  the  maintainability and
     ease of use of these subsystems.

Comments should be sent to the author:

via Multics Mail:
   Margulies at either System-M, MIT, or CISL-SERVICE.

via Forum:
   >udd>m>mtgs>B2 on System-M

via telephone:
   (HVN) 261-9333, or
   (617) 492-9333


Multics  project  internal  working  documentation.   Not  to  be
reproduced or distributed outside the Multics project without the
consent of the author or the author's management.

MTB-694                                Multics Technical Bulletin
                              SSU_ SC, IOX MC, Logging Admin Mode


The  system  control  environment  is the  set  of  programs that
execute commands in the Initializer process.  These programs have
three tasks:   Reading commands, parsing  and executing commands,
and  appropriately  routing command  output.  System  control was
originally  invented  before  the Message  Coordinator,  and then
adapted to work with it.  The adaptation has some problems.


3.1 Reading commands

There are  two ways that  commands typed by operators  get to the
Initializer  for  execution:  the  "system" console,  and message
coordinator  terminals.  The  system console is  attached via the
ocd_  I/O module  to an I/O  switch named  master_i/o, whose IOCB
pointer is stored  in sc_stat_$master_iocb.  system_control_, the
Initializer's   ring  4   process  overseer,   reads  lines  from
master_i/o  and  then  passes  them off  for  execution.  Message
coordinator  terminals  are  run  by the  message  coordinator by
direct calls  to hcs_$tty*.  mc_tty_ reads  commands when it gets
wakeups from the hardcore and passes the results off.

3.2 Executing commands

Commands are  executed by calls  to two programs:   sc_parse_ and
execute_sc_command_.   sc_parse_  uses  an include  file  full of
internal  static constants  to identify commands.   It returns an
index uniquely identifying the command and some other information
about  it.   This information  is passed  to execute_sc_command_.
Execute_sc_command_  either  executes  the command  in  place, or
calls  the  normal Multics  command processor  on a  command line
fabricated  by  replacing  the  initializer command  name  with a
character string supplied by sc_parse_.

The  modularity  of this  is not  very good,  since the  calls to
sc_parse_ and  execute_sc_command_ are duplicated  in mc_tty_ and

3.3 I/O switches for commands

The problems with the current design are primarily concerned with
the   setup  of   I/O  switches  for   command  execution.   Most
initializer commands are just  Multics commands repackaged.  They
expect  to do  output, and in  some cases input,  on the standard

Multics Technical Bulletin                                MTB-694
SSU_ SC, IOX MC, Logging Admin Mode

switches.  Further,  input must be  read from the  terminal where
the operator typed the command.  Since  there can only be one set
of  user_i/o,  user_input, user_output,  and error_output  in the
process, these switches must be rearranged for each command.  For
commands  that  never read,  the  switches are  left  alone.  All
user_i/o is connected to a switch named "mc_i/o", which is routed
as the message coordinator "sc" source.

For commands that can read, the switches have to be rearranged so
that  they are  attached to the  terminal that  sent the command.
For  the  system console  this is  a matter  of using  syn_.  For
message  coordinator terminals,  this is complicated  by the fact
that it  is running the  terminals through hcs_.  It  must make a
tty_ attachment before executing the  command and then release it
afterwards.  This hairy mechanism  is implemented by the programs
borrow_tty_from_mc_  and return_tty_to_mc_.   This mechanism does
not work  correctly if a  terminal hangs up in  a borrowed state.
The system can end up hung if a terminal hangs up in admin mode.

3.4 Command Output

Command output  is also complicated.  Commands  that were written
just for system control call  the sys_log_ subroutine for output.
That  subroutine writes  all output  to the  message coordinator.
This  has  two problems.   First,  no message  coordinator output
comes  out  until  after  the  command  finishes  execution.  The
message   coordinator  is   an  asynchronous   subsystem  of  the
Initializer,  and   all  such  subsystems   are  inhibited  while
executing  commands  to avoid  the need  for locks.   Second, the
message coordinator  cannot send the output  back to the terminal
where  the command  came from.  It  just goes  wherever the three
severity switches (or "sc") are routed.


The  new system  control structure will  simplify this situation,
both  from  the  point of  view  of code  structure  and operator
interface.  Nearly all command output will return to the terminal
that  originated the  command.  Initializer  commands (other than
reply and intercom) will be able to use command processor special
characters.   Online   help  will  be   available.   The  complex
borrow_tty_from_mc_ mechanism will be removed.

4.1 Reading commands

system_control_ will  continue to read lines  from master_i/o via
iox_.   The  message coordinator  will be  changed to  remove all

MTB-694                                Multics Technical Bulletin
                              SSU_ SC, IOX MC, Logging Admin Mode

calls to  hcs_$tty_*.  Instead, it  will attach a  switch to each
"accepted"  terminal,  and use  iox_.  It  will use  timed_io_ to
avoid  blocking.   It will  not  use -no_block,  because commands
reading  input  need  to  block.   It  will  handle  line_status.
Currently,  using a  sty as a  message coordinator  terminal is a
good  way  to  kill  the system,  since  the  message coordinator
explodes when a line_status arrives.

4.2 Executing commands

ssu_   will  be   used  to  interpret   commands.   Each  message
coordinator   terminal   will   have   an   associated  subsystem
invocation.   The  static  variable  sc_stat_$admin_sci_ptr  will
contain the  sci_ptr for the currently  executing command.  If no
command is executing, this value  will be null.  The ssu_ request
table  will  use user  flags  to define  the  message coordinator
restrictions, as described in detail below.

The  program  sc_process_command_line_  is  the  replacement  for
sc_parse_  and execute_sc_command_.   system_control_ and mc_tty_
call  this  program  with  the  command  line.   It  sets  up the
environment,    establishes    cleanup   handlers,    and   calls
ssu_$execute_line  to perform  the actual execution.   As part of
setup,  the  standard I/O  switches are  connected to  the source
terminal.   As  part  of   cleanup,  the  previous  switches  are
restored.   Thus,  even aborted  file outputs  cannot permanently
swallow output.

The   program  sc_execute_command_line_   is  set   as  the  ssu_
"execute_line"  procedure.   It implements  the  required special
handling of  the reply and  intercom commands, and  also enforced
terminal privilege restrictions and operator login.

4.3 Command Output

Command output appears  in one of two ways:   I/O to the standard
switches,   and  calls   to  sys_log_.   sc_process_command_line_
attaches user_i/o to signal_io_ to catch all activity.  All input
and  output  is  logged in  >sc1>as_logs>admin_log,  before being
passed along to the switch for the source terminal.

sys_log_  poses a  problem.  Some  of the  calls to  sys_log_ are
intended to produce real Answering  Service log messages, with or
without  output  through  the  message  coordinator.   Others are
intended as responses to typed commands.  A survey of the callers
of  sys_log_  revealed that  no  analysis of  the  currently used
severity codes would reliably sort the one from the other.

Multics Technical Bulletin                                MTB-694
SSU_ SC, IOX MC, Logging Admin Mode

Instead,   two   new   entrypoints   are   added   to   sys_log_:
sys_log_$command and sys_log_$command_error.  These have the same
calling    sequence    as   sys_log_    and   sys_log_$error_log,
respectively.   Calls to  the new entrypoints  are interpreted as
producing  responses  to commands.   The  output is  sent  to the
source terminal and  logged in the admin_log, but  is NOT sent to
the message  coordinator for further distribution.   Calls to the
old  entrypoints are  interpreted as  real log  messages, and are
sent to the Answering Service  log and the message coordinator as

All the  initializer commands that call  sys_log_ are implemented
in admin_.pl1 and  a few things it calls,  so that converting the
sys_log_ calls is not hard.

4.4 Admin Mode

This design  for I/O handling  will result in the  logging of all
admin mode traffic,  so long as the operator  does not manipulate
the I/O  switches.  We cannot protect  against such manipulations
without a really enormous effort.


As  part  of these  changes,  the Answering  Service log  and all
message coordinator  logs are converted  to the new  (mtb666) log
format.  The  print_log command cannot be  made compatable, since
the  field may  have its  own applications  that use  the old log
format.  The new print_sys_log command will be used for printing,
and monitor_sys_log for monitoring.  See below for details.

Other  small  bug fixes  and  enhancements are  described  in the
detailed descriptions below.

Some  changes  are made  to  ssu_ and  tty_  to support  this, as
described in the following subsections:

5.1 tty_ changes

     There is a new control argument pair for tty_.

This control  argument prevents tty_ from  using dial_manager_ to
attach the  specified channel.  If  the channel cannot  be attach
via a call to hcs_, the attach operation fails.


MTB-694                                Multics Technical Bulletin
                              SSU_ SC, IOX MC, Logging Admin Mode

This enables dial_manager_, and is the default.

In  addition  a  series of  bugs  in the  tty_  implementation of
timed_io_  support are  fixed so  that specifying  a zero timeout
value means "try once, and then return the results."

5.2 ssu_ changes

Several changes are made to  ssu_ to support this design.  First,
the user flags are added back  to the request macros.  (They were
deleted  in a  previous change.)  These  are used  in the request
table to note the requirements  of each request for privilege and
system   startup  state.    Second,  the   set_default_flags  and
set_default_multics_flags  macros are  added.  These  are a great
convienience.     Third,    the    get_subsystem_and_request_name
procedure  is  made  replaceable.    This  allows  messages  from
requests   to   say   (for   example)   "word:    "   instead  of
"system_control  (word):".  Complete  documentation for  these is
provided in an MCR.

5.3 Detailed Descriptions of the Design

This  section  describes  the  new design  in  detail,  module by


This bound module contains the system control environment proper. system_control_

This  is  the  Initializer's  ring  4  process  overseer.   After
initializing  the environment  with sc_init_,  it sits  in a loop
calling iox_$get_line  and sc_process_command_line_.  A  label in
this program is stored  in sc_stat_$shutdown_label.  The shutdown
request  goes  to  this  label  so  that  the  command  execution
environment will  be cleaned up before  shutdown runs.  A handler
for  any_other  calls  sc_signal_handler_,   and  a  handler  for
signal_io_ calls sc_signal_io_handler_. sc_init_

This program sets up the pre-message coordinator environment.  It
attaches the  system console via  ocd_ to the  switch master_i/o,
and three severity switches (severity1, severity2, severity3) via

Multics Technical Bulletin                                MTB-694
SSU_ SC, IOX MC, Logging Admin Mode

syn_  to  master_i/o.  The  standard switches  (user_input, etc.)
are  set  as  syn_'s  to master_i/o.   It  creates  the subsystem
invocation for  the system console via  a call to sc_create_sci_.
It opens the answering service log and the admin log.

     If  it  succeeds in  setting up  the basic  attachments, but
fails  to do  something else, it  attempts to set  up a primitive
"admin  mode"  to allow  maintainers to  fix the  problem without
having to reload from tape. sc_create_sci_

This  procedure  creates  and destroys  system  control subsystem
invocations.   A  system  control  subsystem  invocation  has the
following characteristics:

  *  The      info      structure,      as      described      by
     sc_subsystem_info_.incl.pl1.  This structure stores the IOCB
     for the source terminal of a command execution, the replaced
     ssu_ procedures  for execute_line and  locate_request, and a
     procedure to call if the terminal hangs up while executing a
     command.   The  message  coordinator  restriction  flags are
     copied  here  by  mc_commands_  from  the  mc  answer  table
     (mc_ate) entry, and a pointer to the mc_ate entry is kept.

  *  The     execute_line     procedure     is     replaced    by
     sc_execute_command_line_.  execute_line is  replaced so that
     the   special   commands,   reply  and   intercom,   can  be
     implemented.   These requests  do not  parse their arguments
     normally,  and  so cannot  be passed  to the  normal command

  *  The  locate_request procedure  is replaced  to implement the
     message  coordinator  command restrictions.   It  checks the
     message coordinator command restriction flags in the request
     table against the restriction flags in sc_subsystem_info_ to
     see  if  the source  terminal  is permitted  to  execute the
     request.   As explained  below, each request  in the request
     table  is  tagged with  the  terminal privilege  required to
     execute it.  It also check for operator login as needed.

  *  The              request              tables             are
     sc_request_table_$system_control_requests  and  the standard
     request  table.  The  info directories  are >doc>initializer
     and the standard info directory.  ".."  is disabled, and the
     execute request is removed.

  *  The get_subsystem_and_request_name procedure  is replaced to

MTB-694                                Multics Technical Bulletin
                              SSU_ SC, IOX MC, Logging Admin Mode

     make  all  error  messages  begin with  the  string COMMAND:
     instead of "system control (COMMAND):". sc_request_table_

This is  the request table  for all of  the initializer commands.
All   of   the   requests   that   used   to   be   implented  by
execute_sc_command_ are  "ordinary" requests.  All  requests that
were  implemented  by  calling  the  command  processor  are  now
multics_requests.  The only problem here is the who request.  The
old  mechanism  added the  -long control  argument to  the as_who
command line.   I propose to  make -long the  default for as_who,
since  if you  don't say  -long you might  as well  have used the
normal who command.

A set of user flags are  used to store the restriction classes of
the commands and whether or  not they depend on answering service
initialization.   Each  command  is  classified  as  requiring  a
particular privilege.  There  is a set of 36  bits in the mc_ate,
one  per  privilege.   The  "accept"  command  takes  an optional
argument which specifies which of the flags to enable.

A bunch of strange undocumented requests are removed.  A bunch of
wierd undocumented  short names are replaced  by reasonable short
names.  See the appendix for the complete list of requests in the
final version. sc_signal_io_handler_

This  module  catches all  signal_io_  signals.  If  there  is no
command active, it  ignores them.  If there is  a command active,
it  logs  the  traffic in  the  admin_log and  then  forwards the
request     to    the     real    switch,     as    defined    by
sc_subsystem_info.real_iocb. sc_process_command_line_

This is the interface for executing  a command that was read from
a  terminal.   The  terminal is  defined  by the  mc_atep  in the
sc_subsystem_info  associated  with  the   sci_ptr  passed  as  a
parameter.  All  the standard switches are  saved and reattached.
The hangup_entry  in the sc_subsystem_info is  set to an internal
procedure  that  non-local goes  to  a label.   This  unwinds the
command  execution.   An  error   message  is  printed,  and  the
environment is cleaned up.

Multics Technical Bulletin                                MTB-694
SSU_ SC, IOX MC, Logging Admin Mode

The  command  is  executed   via  a  call  to  ssu_$execute_line.
ssu_$execute_line  setsa  up  appropriate  handlers  for  request
aborts and  the line and then  calls the replaceable execute_line
procedure, which is sc_execute_command_line_.

Note  that  neither  sc_command not  sc_admin_command_  call this
program.    sc_command   assumes  that   switches  are   set  up.
sc_admin_command_ sets up switches for  itself, as explained in a
previous MTB.

This program  implements a crucial  Answering Service programming
convention, that of the rules  for blocking.  The Initializer may
not go  blocked with event  calls unmasked except  while awaiting
the  input  of  a  command.   Thus,  the  two  places  where  the
Initializer may block  with event calls unmasked are  in the call
to   iox_$get_line  in   system_control_  and  in   the  call  to
iox_$get_line in  sc_admin_mode_.  This rule  guarantees that the
code that implements the initializer  commands may not be entered
recursively.  The  Initializer may block with  event calls masked
anyplace,  but the  code must  guarantee that  the block  will be
satisfied in a reasonable period of time.

There  is one  exception to this  rule.  The I/O  module mr_ must
exchange  wakeups with  the program  mc_wakeups_ to  complete the
attachment of a switch.  When the Initializer runs turn_on_mc_ to
attach  the three  severity switches via  mr_, it  must unmask so
that  mc_wakeups_  will  receive   the  wakeup  sent  by  mrdim_.
Otherwise, the system would hang. sc_execute_command_line_

This procedure contains the entrypoints that replace execute_line
and  locate_request, respectively.   The execute_line entrypoint,
which is the main entrypoint, peeks into the command line to find
the  request  name.  It  looks it  up in  the request  table, and
checks to see  if it has the dont_parse_arguments  user flag.  If
so, it specially invokes it.

If  the request  is not  special, or  the request  name cannot be
determined  (e.g.,  "[foo] bas  baz"), the  standard execute_line
procedure stored in sc_subsystem_info is called.

The  locate_request entrypoint  will be called  when the standard
execute_line  procedure  wishes to  look up  a request  name.  It
calls the standard locate_request stored in the sc_subsystem_info
to  make the  table lookup.   Then it  makes a  series of checks.
First,  if a  dont_parse_arguments request  is found  here, it is
invalid.  ("who;reply foo bar" is not valid) Then, it checks that
the Answering Service is available  if needed, or not started for

MTB-694                                Multics Technical Bulletin
                              SSU_ SC, IOX MC, Logging Admin Mode

the  multics  and  start_up  requests.   Finally,  it  checks the
message  coordinator  restrictions  for   the  terminal  and  the
operator  login state.   If all the  checks pass,  it returns the
request data.  Otherwise it aborts the request. Other procedures

The other procedures in bound_system_control_ are utilities of no
great  importance.   Note  that  sc_admin_mode_,  that implements
admin mode, now enables quits on the terminal during admin mode.

5.3.2 BOUND_AS_MC_

This  bound  segment  contains all  of  the contents  of  the old
bound_oprcons_    except    for    sys_log_,    write_log_    and
dial_manager_call.   sys_log_ is  moved to bound_system_control_,
write_log_    to    >obsolete,     and    dial_manager_call    to
bound_as_requests_.  Only a few programs in here are changed: mc_commands_

mc_commands_  provides   subroutines  that  are   called  by  the
message-coordinator-related commands in admin_.pl1.  This program
actually does  the work of accepting  and dropping terminals, and
is converted to use iox_ as  needed.  It attaches a switch when a
channel is accepted.   (There is one execption --  if the mpx has
never been loaded, the attach fails, and is retried at mpx load.)
If the  channel is dialed  up, it sends  a wakeup over  the event
channel to  get mc_tty_ to  pay attention.  Otherwise,  it does a
listen control order, and the hardcore sends the wakeup.  Various
minor problems  are cleaned up  in here.  The  vcons manipulators
are   changed  to   call  log_write_   to  open   and  close  log
destinations. mc_tty_

This is  the read side of  message coordinator terminal handling.
It does NOT handle input for the system console.  It is converted
to  call  iox_  and  timed_io_,  and  it  handles  all answerback
processing.   The  flag  mc_anstbl.trace enables  tracing  in the
program,   which  can   be  useful  in   debugging.   It  handles
line_status errors  by looping making  line_status control orders
and  discarding the  line_status.  It handles  hangups by calling
the  subsystem  invocation hangup  procedure if  and only  if the
subsystem associated with the channel is currently executing.

Multics Technical Bulletin                                MTB-694
SSU_ SC, IOX MC, Logging Admin Mode mc_wakeups_

This  programs  handles a  variety  of message  coordinator event
driven  functions.  The  only one  changed was  output to message
coordinator terminals and logs.  As with everything else, this is
converted  to  timed_io_ for  terminals and  iox_ for  the system
console.  Log messages are written with calls to log_write_.

5.3.3 ADMIN_.PL1

admin_,  all  30  records  of  pl1  source,  implements  all  the
initializer  commands  that  are   not  just  repackaged  Multics
commands.  All calls to  sys_log_ and sys_log_$error_log here are
converted to calls to entry variables.  These entry variables are
normally set to the command entrypoints in sys_log_.

There are several cases where admin_  is called from a timer.  In
these  cases, the  entry variables  are reset  to the non-command
entrypoints  in sys_log_.   Several common stretches  of code are
moved into internal  procedures to make this work  right, and all
calls to cu_$arg* are changed  to cu_$arg_*_rel to make THAT work
right.  Some  trivial bugs in  argument processing are  fixed, as
well.  In particular, the "accept" command can once again be used
to  change  the  restriction  or broadcast  state  of  an already
accepted terminal.

5.4 Appendix:  List of all initializer commands

     This list  is in loose functional  order.  The standard ssu_
list_requests request lists the requests  in the order they occur
in the tables, not in alpha  order.  It would be simple to change
the request table to be alphabetized if people preferred it.

Summary of system_control requests:

Type "list_help" for a list of topics available to the help request.
Type "help TOPIC" for more information on a given topic.

sign_on                  Sign in as the operator responsable for
                         this terminal.
sign_off                 Sign out as the operator responsable for
                         this terminal.
reply, r                 Send input to a daemon process.
admin                    Enter admin mode.
bce                      Return to BCE.
force_reset              Force reset Answering Service locks and
go                       Start answering lines.

MTB-694                                Multics Technical Bulletin
                              SSU_ SC, IOX MC, Logging Admin Mode

message, motd            Edit the message of the day.
multics                  Initialize the Answering Service for a
                            special session.
reset                    Reset some Answering Service locks and
shutdown, shut           Shut down the system.
startup, star            Start the Answering Service and begin
                            answering lines.
cripple                  Stop the Answering Service. For use
                         in an emergency, only.
intercom, ic             Send a message to another message
                            coordinator terminal.
exec, x                  Executes an extended command.
hmu                      Prints the number of users logged in.
list_vols, lsv           Status of storage system.
who                      Lists logged in user.
login, logi              Logs in a daemon process.
logout, logo             Logs out a daemon process.
word                     Changes the login word and banner message.
sysid                    Changes the system ID.
down                     Sets, cancels, or prints the scheduled
                            shutdown time.
stop                     Bump users in preparation for system
warn, w                  Sends a warning blast to a user.
maxunits, maxu           Set the maximum number of users who may
detach                   Forcibly detach a communications channel
                            from a user.
terminate, term          Forcibly terminate a process.
bump                     Bump an interactive user from the system.
unbump, unbmp            Cancel a bump of an interactive user.
attach                   Attach a communications channel for use.
remove                   Remove a channel from use.
accept                   Accept a channel as a message coordinator
substty, subs            Substitute one message coordinator terminal
                            for another.
drop                     Drop a channel from use as a message
                            coordinator terminal.
define                   Define a new virtual console, or add a
                            disposition to an existing one.
redefine                 Replace the disposition of a virtual
undefine                 Remove a disposition from a virtual
route                    Route a source stream to a virtual console.
reroute                  Change the routing of a source stream.
deroute                  Remove a routine of a source stream.
abs                      Control the absentee facility.

Multics Technical Bulletin                                MTB-694
SSU_ SC, IOX MC, Logging Admin Mode

rcp                      Control RCP.
mc_list                  Lists message coordinator information.
add_vol, av              Inform the system of the location of a
                            physical volume.
add_lv, alv              Mount a logical volume for use.
del_vol, dv              Demount a physical volume.
del_lv, dlv              Demount a logical volume.
init_vol                 Initialize a new physical volume.
salvage_vol              Physical volume salvage a volume.
list_disks, ld           Print the status of all disks.
set_drive_usage, sdu     Change a disk between user I/O and Storage
                            System use.
preload                  Preload a disk or tape volume.
unload                   Unload a disk or tape volume.
load_mpx                 Loads a multiplexer.
dump_mpx                 Dumps a multiplexer.
start_mpx                Starts a multiplexer.
stop_mpx                 Stops a multiplexer from accepting new
add_pdir_volume          Adds a logical volume to the set of pdir
del_pdir_volume          Deletes a logical volume from the set of
                            pdir volumes.
set_pdir_volumes         Specifies the set of pdir logical volumes.
log                      Adds a message to the system log.
shift                    Changes the shift.
disconnect               Forcibly disconnects a user from their
vacate_pdir_volume       Moves all user process directories off of a
                            logical volume.
shutdown_mpx             Shuts down a multiplexer without dumping
add                      Adds hardware for use by the system.
delete, dl               Deletes hardware from use by the system.
.                        Identify the subsystem.
help                     Obtain detailed information on the
list_help, lh            List topics for which help is available.
list_requests, lr        List brief information on subsystem
do                       Perform substitution into a request line
                            before execution.
if                       Conditionally execute one of two request
answer                   Provide preset answers to another request
?                        Produce a list of the most commonly used