mach.subproj/servers.subproj/bootstrap.defs

   1 /*
   2  * bootstrap -- fundamental service initiator and port server
   3  * Mike DeMoney, NeXT, Inc.
   4  * Copyright, 1990.  All rights reserved.
   5  *
   6  * bootstrap.defs -- Mig interface definition
   7  */
   8
   9 subsystem bootstrap 400;
  10
  11 /*
  12  *      Interface:      Bootstrap server
  13  *
  14  *  The bootstrap server is the first user-mode task initiated by the Mach
  15  *  kernel at system boot time.  The bootstrap server provides two services,
  16  *  it initiates other system tasks, and manages a table of name-port bindings
  17  *  for fundamental system services  (e.g. the NetMsgServer, and the Unix
  18  *  emulation service).
  19  *
  20  *  The file /etc/bootstrap.conf is read by bootstrap to determine other system
  21  *  services to initiate at system boot time.  The format of this file is
  22  *  described later.
  23  *
  24  *  Name-port bindings can be established with the bootstrap server by either
  25  *  of two mechanisms:
  26  *
  27  *  1.  The binding can be indicated in the file /etc/bootstrap.conf.  In this
  28  *  case, bootstrap will immediately create a port and bind the indicated name
  29  *  with that port.  At a later time, a service may "checkin" for the name-port
  30  *  binding and will be returned receive rights for the bound port.  Lookup's
  31  *  on bindings created by this mechanism will return send rights to the port,
  32  *  even if no service has "checked-in".  In this case, requests sent to the
  33  *  bound port will be queued until a server has checked-in and can satisfy the
  34  *  request.
  35  *
  36  *  2.  Bindings can be established dynamically via a "register" request.  In
  37  *  this case, the register request provides bootstrap with a name and send
  38  *  rights for a port.  Bootstrap will provide send rights for the bound port
  39  *  to any requestor via the lookup request.
  40  *
  41  *  Bootstrap provides its service port to descendant tasks via the Mach
  42  *  "bootstrap" special task port.  All direct descendants of bootstrap receive
  43  *  a "privileged" bootstrap service port.  System services that initiate
  44  *  untrusted tasks should replace the Mach bootstrap task special port with
  45  *  a subset bootstrap port to prevent them from infecting the namespace.
  46  *
  47  *  The bootstrap server creates a "backup" port for each service that it
  48  *  creates.  This is used to detect when a checked out service is no longer
  49  *  being served.  The bootstrap server regains all rights to the port and
  50  *  it is marked available for check-out again.  This allows crashed servers to
  51  *  resume service to previous clients.  Lookup's on this named port will
  52  *  continue to be serviced by bootstrap while holding receive rights for the
  53  *  bound port.  A client may detect that the service is inactive via the.
  54  *  bootstrap status request.  If the service re-registers rather than
  55  *  "checking-in" the original bound port is destroyed.
  56  *
  57  *  The status of a named service may be obtained via the "status" request.
  58  *  A service is "active" if a name-port binding exists and receive rights
  59  *  to the bound port are held by a task other than bootstrap.
  60  *
  61  *  Bootstrap initiates server tasks and creates initial name-port bindings as
  62  *  directed by the configuration file /etc/bootstrap.conf.  This file has
  63  *  entries with the following formats:
  64  *
  65  *      services [ SERVICE_NAME ]+ ;
  66  *
  67  *              E.g:
  68  *              services OldService=1 SomeService;
  69  *
  70  *              Creates a port and binds the name "OldService" to it.
  71  *              For compatability, assigns the port via mach_ports_register to
  72  *              slot 1.  Also creates a port and binds the name "SomeService".
  73  *
  74  *      self [ SERVICE_NAME ]+ ;
  75  *
  76  *              E.g:
  77  *              self BootStrapService;
  78  *
  79  *              Provides a binding to bootstrap's own service port named
  80  *              "BootStrapService".
  81  *
  82  *      [restartable] server SERVER_FILE_AND_ARGS [ services ... ] ;
  83  *
  84  *              E.g:
  85  *              server "/usr/etc/sigserver -i" services UnixSignalService;
  86  *
  87  *              Initiates the server task "/usr/etc/sigserver" with
  88  *              command-line argument "-i", and also creates a name-port
  89  *              binding for the name UnixSignalService.  Checkin requests for
  90  *              UnixSignalService are only accepted via the bootstrap service
  91  *              port passed to/usr/etc/sigserver.  If the "restartable" option
  92  *              had been specified, bootstrap will reinitiate the server task
  93  *              if it receives notification that all of the server's service
  94  *              ports have been destroyed or deallocated.  The server command
  95  *              may be specified without surrounding quotes if it does not
  96  *              include blanks.
  97  *
  98  *      init SERVER_FILE_AND_ARGS [ services ... ] ;
  99  *
 100  *              E.g:
 101  *              init /etc/init services NetMsgService=0 PSWindowService=4;
 102  *
 103  *              Functions like "server" request above, except process is
 104  *              started as pid 1.  Illegal if bootstrap itself was not
 105  *              initiated as pid 1.
 106  *
 107  *      forward;
 108  *
 109  *              If present, bootstrap will forward unknown lookup requests to
 110  *              its bootstrap service port (if not PORT_NULL), and forward any
 111  *              reply to the original requester.
 112  *
 113  *      # Comment string up to end of line.
 114  *
 115  *              A line terminated comment starts with a sharp sign (#).
 116  *
 117  *  Lexical notes:  Strings are either enclosed in double quotes ("), or must
 118  *  start with a letter or underscore (_) and followed by a string of
 119  *  alphanumerics and underscores; backslash (\) escapes the following
 120  *  character.  Strings are limited to a (large) length.  Numbers must be
 121  *  decimal.  Blanks and newlines may be freely used outside of strings.
 122  */
 123
 124 #include <mach/std_types.defs>
 125 import <servers/bootstrap_defs.h>;
 126
 127 type name_t             = c_string[128];
 128 type name_array_t       = ^array [] of name_t;
 129 type bool_array_t       = ^array [] of boolean_t;
 130
 131 serverprefix x_;
 132
 133 /*  old service_checkin */
 134 skip;
 135 /*  old service_status */
 136 skip;
 137
 138 /*
 139  * kern_return_t
 140  * bootstrap_check_in(mach_port_t bootstrap_port,
 141  *                   name_t service_name,
 142  *                   port_all_t *service_port)
 143  *
 144  * Returns all rights to service_port of service named by service_name.
 145  *
 146  * Errors:      Returns appropriate kernel errors on rpc failure.
 147  *              Returns BOOTSTRAP_UNKNOWN_SERVICE, if service does not exist.
 148  *              Returns BOOTSTRAP_NOT_PRIVILEGED, if request directed to
 149  *                      bootstrap port without privilege.
 150  *              Returns BOOTSTRAP_SERVICE_ACTIVE, if service has already been
 151  *                      registered or checked-in.
 152  */
 153 routine bootstrap_check_in(
 154                         bootstrap_port  : mach_port_t;
 155                         service_name    : name_t;
 156                 out     service_port    : mach_port_move_receive_t);
 157
 158 /*
 159  * kern_return_t
 160  * bootstrap_register(mach_port_t bootstrap_port,
 161  *                    name_t service_name,
 162  *                    mach_port_t service_port)
 163  *
 164  * Registers send rights for the port service_port for the service named by
 165  * service_name.  Attempts to registering a service where an active binding
 166  * already exists are rejected.  On the otherhand, registering a service where
 167  * and inactive binding exists (i.e. bootstrap currently holds receive rights
 168  * for the service port) is allowed; in this case the previous service port
 169  * will be deallocated.  Restarting services wishing to resume service for
 170  * previous clients must first attempt to checkin to the service in order to
 171  * recover the previous service port.
 172  *
 173  * Errors:      Returns appropriate kernel errors on rpc failure.
 174  *              Returns BOOTSTRAP_NOT_PRIVILEGED, if request directed to
 175  *                      bootstrap port without privilege.
 176  *              Returns BOOTSTRAP_NAME_IN_USE, if service has already been
 177  *                      register or checked-in.
 178  */
 179 routine bootstrap_register(
 180                 bootstrap_port  : mach_port_t;
 181                 service_name    : name_t;
 182                 service_port    : mach_port_t);
 183
 184 /*
 185  * kern_return_t
 186  * bootstrap_look_up(mach_port_t bootstrap_port,
 187  *                  name_t service_name,
 188  *                  mach_port_t *service_port)
 189  *
 190  * Returns send rights for the service port of the service named by
 191  * service_name in service_port.  Service is not guaranteed to be active.
 192  *
 193  * Errors:      Returns appropriate kernel errors on rpc failure.
 194  *              Returns BOOTSTRAP_UNKNOWN_SERVICE, if service does not exist.
 195  */
 196 routine bootstrap_look_up(
 197                 bootstrap_port  : mach_port_t;
 198                 service_name    : name_t;
 199         out     service_port    : mach_port_t);
 200
 201 /*
 202  * kern_return_t
 203  * bootstrap_look_up_array(mach_port_t bootstrap_port,
 204  *                        name_array_t service_names,
 205  *                        int service_names_cnt,
 206  *                        port_array_t *service_port,
 207  *                        int *service_ports_cnt,
 208  *                        boolean_t *all_services_known)
 209  *
 210  * Returns port send rights in corresponding entries of the array service_ports
 211  * for all services named in the array service_names.  Service_ports_cnt is
 212  * returned and will always equal service_names_cnt (assuming service_names_cnt
 213  * is greater than or equal to zero).
 214  *
 215  * Errors:      Returns appropriate kernel errors on rpc failure.
 216  *              Returns BOOTSTRAP_NO_MEMORY, if server couldn't obtain memory
 217  *                      for response.
 218  *              Unknown service names have the corresponding service port set
 219  *                      to PORT_NULL.
 220  *              If all services are known, all_services_known is true on
 221  *                      return, if any service is unknown, it's false.
 222  */
 223 routine bootstrap_look_up_array(
 224                 bootstrap_port  : mach_port_t;
 225                 service_names   : name_array_t;
 226         out     service_ports   : mach_port_array_t;
 227         out     all_services_known: boolean_t);
 228
 229 /*  old bootstrap_get_unpriv_port */
 230 skip;
 231
 232 /*
 233  * kern_return_t
 234  * bootstrap_status(mach_port_t bootstrap_port,
 235  *                  name_t service_name,
 236  *                  boolean_t *service_active);
 237  *
 238  * Returns: service_active is true if service is available.
 239  *
 240  * Errors:      Returns appropriate kernel errors on rpc failure.
 241  *              Returns BOOTSTRAP_UNKNOWN_SERVICE, if service does not exist.
 242  */
 243 routine bootstrap_status(
 244                 bootstrap_port  :       mach_port_t;
 245                 service_name    :       name_t;
 246         out     service_active  :       boolean_t);
 247
 248 /*
 249  * kern_return_t
 250  * bootstrap_info(port_t bootstrap_port,
 251  *                name_array_t *service_names,
 252  *                int *service_names_cnt,
 253  *                name_array_t *server_names,
 254  *                int *server_names_cnt,
 255  *                bool_array_t *service_active,
 256  *                int *service_active_cnt);
 257  *
 258  * Errors:      Returns appropriate kernel errors on rpc failure.
 259  */
 260 routine bootstrap_info(
 261                 bootstrap_port  : mach_port_t;
 262         out     service_names   : name_array_t, dealloc;
 263         out server_names        : name_array_t, dealloc;
 264         out service_active      : bool_array_t, dealloc);
 265
 266 /*
 267  * kern_return_t
 268  * bootstrap_subset(mach_port_t bootstrap_port,
 269  *                  mach_port_t requestor_port,
 270  *                  mach_port_t *subset_port);
 271  *
 272  * Returns a new port to use as a bootstrap port.  This port behaves
 273  * exactly like the previous bootstrap_port, except that ports dynamically
 274  * registered via bootstrap_register() are available only to users of this
 275  * specific subset_port.  Lookups on the subset_port will return ports
 276  * registered with this port specifically, and ports registered with
 277  * ancestors of this subset_port.  Duplications of services already
 278  * registered with an ancestor port may be registered with the subset port
 279  * are allowed.  Services already advertised may then be effectively removed
 280  * by registering PORT_NULL for the service.
 281  * When it is detected that the requestor_port is destroied the subset
 282  * port and all services advertized by it are destroied as well.
 283  *
 284  * Errors:      Returns appropriate kernel errors on rpc failure.
 285  */
 286 routine bootstrap_subset(
 287                 bootstrap_port  : mach_port_t;
 288                 requestor_port  : mach_port_t;
 289         out     subset_port     : mach_port_t);
 290
 291 /*
 292  * kern_return_t
 293  * bootstrap_create_service(mach_port_t bootstrap_port,
 294  *                    name_t service_name,
 295  *                    mach_port_t *service_port)
 296  *
 297  * Creates a service named "service_name" and returns send rights to that
 298  * port in "service_port."  The port may later be checked in as if this
 299  * port were configured in the bootstrap configuration file.
 300  *
 301  * Errors:      Returns appropriate kernel errors on rpc failure.
 302  *              Returns BOOTSTRAP_SERVICE_ACTIVE, if service already exists.
 303  */
 304 routine bootstrap_create_service(
 305                 bootstrap_port  : mach_port_t;
 306                 service_name    : name_t;
 307         out     service_port    : mach_port_t);