liblaunch/bootstrap.h

   1 #ifndef __BOOTSTRAP_H__
   2 #define __BOOTSTRAP_H__
   3 /*
   4  * Copyright (c) 1999-2005 Apple Computer, Inc. All rights reserved.
   5  *
   6  * @APPLE_APACHE_LICENSE_HEADER_START@
   7  *
   8  * Licensed under the Apache License, Version 2.0 (the "License");
   9  * you may not use this file except in compliance with the License.
  10  * You may obtain a copy of the License at
  11  *
  12  *     http://www.apache.org/licenses/LICENSE-2.0
  13  *
  14  * Unless required by applicable law or agreed to in writing, software
  15  * distributed under the License is distributed on an "AS IS" BASIS,
  16  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  17  * See the License for the specific language governing permissions and
  18  * limitations under the License.
  19  *
  20  * @APPLE_APACHE_LICENSE_HEADER_END@
  21  */
  22
  23 /*
  24  * bootstrap -- fundamental service initiator and port server
  25  * Mike DeMoney, NeXT, Inc.
  26  * Copyright, 1990.  All rights reserved.
  27  */
  28
  29 /*
  30  *      Interface:      Bootstrap server
  31  *
  32  *  The bootstrap server is the first user-mode task initiated by the Mach
  33  *  kernel at system boot time.  The bootstrap server provides two services,
  34  *  it initiates other system tasks, and manages a table of name-port bindings
  35  *  for fundamental system services  (e.g. lookupd, Window Manager, etc...).
  36  *
  37  *  Name-port bindings can be established with the bootstrap server by either
  38  *  of two mechanisms:
  39  *
  40  *  1.  The binding can be indicated, in advance of the service that backs it
  41  *  being available, via a "service create" request.  In this case, bootstrap
  42  *  will immediately create a port and bind the indicated name with that port.
  43  *  At a later time, a service may "checkin" for the name-port
  44  *  binding and will be returned receive rights for the bound port.  Lookup's
  45  *  on bindings created by this mechanism will return send rights to the port,
  46  *  even if no service has "checked-in".  In this case, requests sent to the
  47  *  bound port will be queued until a server has checked-in and can satisfy the
  48  *  request.
  49  *
  50  *  2.  Bindings can be established dynamically via a "register" request.  In
  51  *  this case, the register request provides bootstrap with a name and send
  52  *  rights for a port.  Bootstrap will provide send rights for the bound port
  53  *  to any requestor via the lookup request.
  54  *
  55  *  Bootstrap provides its service port to descendant tasks via the Mach
  56  *  "bootstrap" special task port.  All direct descendants of bootstrap receive
  57  *  a "privileged" bootstrap service port.  System services that initiate
  58  *  untrusted tasks should replace the Mach bootstrap task special port with
  59  *  a subset bootstrap port to prevent them from infecting the namespace.
  60  *
  61  *  The bootstrap server creates a "backup" port for each service that it
  62  *  creates.  This is used to detect when a checked out service is no longer
  63  *  being served.  The bootstrap server regains all rights to the port and
  64  *  it is marked available for check-out again.  This allows crashed servers to
  65  *  resume service to previous clients.  Lookup's on this named port will
  66  *  continue to be serviced by bootstrap while holding receive rights for the
  67  *  bound port.  A client may detect that the service is inactive via the
  68  *  bootstrap status request.  If an inactive service re-registers rather
  69  *  than "checking-in" the original bound port is destroyed.
  70  *
  71  *  The status of a named service may be obtained via the "status" request.
  72  *  A service is "active" if a name-port binding exists and receive rights
  73  *  to the bound port are held by a task other than bootstrap.
  74  *
  75  *  The bootstrap server may also (re)start server processes associated with
  76  *  with a set of services. The definition of the server process is done
  77  *  through the "create server" request.  The server will be launched in the
  78  *  same bootstrap context in which it was registered.
  79  */
  80 #include <AvailabilityMacros.h>
  81 #include <mach/std_types.h>
  82 #include <mach/message.h>
  83 #include <sys/types.h>
  84 #include <sys/cdefs.h>
  85 #include <stdbool.h>
  86
  87 __BEGIN_DECLS
  88
  89 #pragma GCC visibility push(default)
  90
  91 #define BOOTSTRAP_MAX_NAME_LEN                  128
  92 #define BOOTSTRAP_MAX_CMD_LEN                   512
  93
  94 typedef char name_t[BOOTSTRAP_MAX_NAME_LEN];
  95 typedef char cmd_t[BOOTSTRAP_MAX_CMD_LEN];
  96 typedef name_t *name_array_t;
  97 typedef int bootstrap_status_t;
  98 typedef bootstrap_status_t *bootstrap_status_array_t;
  99 typedef unsigned int bootstrap_property_t;
 100 typedef bootstrap_property_t * bootstrap_property_array_t;
 101
 102 typedef boolean_t *bool_array_t;
 103
 104 #define BOOTSTRAP_MAX_LOOKUP_COUNT              20
 105
 106 #define BOOTSTRAP_SUCCESS                               0
 107 #define BOOTSTRAP_NOT_PRIVILEGED                1100
 108 #define BOOTSTRAP_NAME_IN_USE                   1101
 109 #define BOOTSTRAP_UNKNOWN_SERVICE               1102
 110 #define BOOTSTRAP_SERVICE_ACTIVE                1103
 111 #define BOOTSTRAP_BAD_COUNT                             1104
 112 #define BOOTSTRAP_NO_MEMORY                             1105
 113 #define BOOTSTRAP_NO_CHILDREN                   1106
 114
 115 #define BOOTSTRAP_STATUS_INACTIVE               0
 116 #define BOOTSTRAP_STATUS_ACTIVE                 1
 117 #define BOOTSTRAP_STATUS_ON_DEMAND              2
 118
 119 /*
 120  * After main() starts, it is safe to assume that this variable is always set.
 121  */
 122 extern mach_port_t bootstrap_port;
 123
 124 /*
 125  * bootstrap_create_server()
 126  *
 127  * Declares a server that mach_init will re-spawn within the specified
 128  * bootstrap context.  The server is considered already "active"
 129  * (i.e. will not be re-spawned) until the returned server_port is
 130  * deallocated.
 131  *
 132  * In the meantime, services can be declared against the server,
 133  * by using the server_port as the privileged bootstrap target of
 134  * subsequent bootstrap_create_service() calls.
 135  *
 136  * When mach_init re-spawns the server, its task bootstrap port
 137  * is set to the privileged sever_port.  Through this special
 138  * bootstrap port, it can access all of parent bootstrap's context
 139  * (and all services are created in the parent's namespace). But
 140  * all additional service declarations (and declaration removals)
 141  * will be associated with this particular server.
 142  *
 143  * Only a holder of the server_port privilege bootstrap port can
 144  * check in or register over those services.
 145  *
 146  * When all services associated with a server are deleted, and the server
 147  * exits, it will automatically be deleted itself.
 148  *
 149  * If the server is declared "on_demand," then a non-running server
 150  * will be re-launched on first use of one of the service ports
 151  * registered against it.  Otherwise, it will be re-launched
 152  * immediately upon exiting (whether any client is actively using
 153  * any of the service ports or not).
 154  *
 155  * Errors:      Returns appropriate kernel errors on rpc failure.
 156  *              Returns BOOTSTRAP_NOT_PRIVILEGED, bootstrap or uid invalid.
 157  */
 158 kern_return_t bootstrap_create_server(
 159                 mach_port_t bp,
 160                 cmd_t server_cmd,
 161                 uid_t server_uid,
 162                 boolean_t on_demand,
 163                 mach_port_t *server_port);
 164
 165 /*
 166  * bootstrap_subset()
 167  *
 168  * Returns a new port to use as a bootstrap port.  This port behaves
 169  * exactly like the previous bootstrap_port, except that ports dynamically
 170  * registered via bootstrap_register() are available only to users of this
 171  * specific subset_port.  Lookups on the subset_port will return ports
 172  * registered with this port specifically, and ports registered with
 173  * ancestors of this subset_port.  Duplications of services already
 174  * registered with an ancestor port may be registered with the subset port
 175  * are allowed.  Services already advertised may then be effectively removed
 176  * by registering PORT_NULL for the service.
 177  * When it is detected that the requestor_port is destroyed the subset
 178  * port and all services advertized by it are destroyed as well.
 179  *
 180  * Errors:      Returns appropriate kernel errors on rpc failure.
 181  */
 182 kern_return_t bootstrap_subset(
 183                 mach_port_t bp,
 184                 mach_port_t requestor_port,
 185                 mach_port_t *subset_port);
 186
 187 /*
 188  * bootstrap_unprivileged()
 189  *
 190  * Given a bootstrap port, return its unprivileged equivalent.  If
 191  * the port is already unprivileged, another reference to the same
 192  * port is returned.
 193  *
 194  * This is most often used by servers, which are launched with their
 195  * bootstrap port set to the privileged port for the server, to get
 196  * an unprivileged version of the same port for use by its unprivileged
 197  * children (or any offspring that it does not want to count as part
 198  * of the "server" for mach_init registration and re-launch purposes).
 199  *
 200  * Native launchd jobs are always started with an unprivileged port.
 201  */
 202 kern_return_t bootstrap_unprivileged(
 203                 mach_port_t bp,
 204                 mach_port_t *unpriv_port)
 205                 AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_5;
 206
 207 /*
 208  * bootstrap_parent()
 209  *
 210  * Given a bootstrap subset port, return the parent bootstrap port.
 211  * If the specified bootstrap port is already the root subset,
 212  * the same port will be returned. Much like "." and ".." are the same
 213  * in the file system name space for the root directory ("/").
 214  *
 215  * Errors:
 216  *      Returns BOOTSTRAP_NOT_PRIVILEGED if the caller is not running
 217  *      with an effective user id of root (as determined by the security
 218  *      token in the message trailer).
 219  */
 220 kern_return_t bootstrap_parent(
 221                 mach_port_t bp,
 222                 mach_port_t *parent_port);
 223
 224 /*
 225  * bootstrap_register()
 226  *
 227  * Registers a send right for service_port with the service identified by
 228  * service_name.  Attempts to register a service where an active binding
 229  * already exists are rejected.
 230  *
 231  * If the service was previously declared with bootstrap_create_service(),
 232  * but is not currently active, this call can be used to undeclare the
 233  * service. The bootstrap port used must have sufficient privilege to
 234  * do so.  (Registering MACH_PORT_NULL is especially useful for shutting
 235  * down declared services).
 236  *
 237  * This API is deprecated. Old scenarios and recommendations:
 238  *
 239  * 1) Code that used to call bootstrap_check_in() and then bootstrap_register()
 240  *    can now always call bootstrap_check_in().
 241  *
 242  * 2) If the code was registering a well known name, please switch to launchd.
 243  *
 244  * 3) If the code was registering a dynamically generated string and passing
 245  *    the string to other applications, please rewrite the code to send a Mach
 246  *    send-right directly.
 247  *
 248  * 4) If the launchd job maintained an optional Mach service, please reserve
 249  *    the name with launchd and control the presense of the service through
 250  *    ownership of the Mach receive right like so.
 251  *
 252  *      <key>MachServices</key>
 253  *      <dict>
 254  *              <key>com.apple.windowserver</key>
 255  *              <true/>
 256  *              <key>com.apple.windowserver.active</key>
 257  *              <dict>
 258  *                      <key>HideUntilCheckIn</key>
 259  *                      <true/>
 260  *              </dict>
 261  *      </dict>
 262  *
 263  *
 264  * Errors:      Returns appropriate kernel errors on rpc failure.
 265  *              Returns BOOTSTRAP_NOT_PRIVILEGED, if request directed to
 266  *                      bootstrap port without privilege.
 267  *              Returns BOOTSTRAP_NAME_IN_USE, if service has already been
 268  *                      register or checked-in.
 269  */
 270 AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_5
 271 kern_return_t
 272 bootstrap_register(mach_port_t bp, name_t service_name, mach_port_t sp);
 273
 274 /*
 275  * bootstrap_create_service()
 276  *
 277  * Creates a service named "service_name" and returns a send right to that
 278  * port in "service_port."  The port may later be checked in as if this
 279  * port were configured in the bootstrap configuration file.
 280  *
 281  * This API is deprecated. Please call bootstrap_check_in() instead.
 282  *
 283  * Errors:      Returns appropriate kernel errors on rpc failure.
 284  *              Returns BOOTSTRAP_SERVICE_ACTIVE, if service already exists.
 285  */
 286 #ifdef AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_6
 287 AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_6
 288 #endif
 289 kern_return_t
 290 bootstrap_create_service(mach_port_t bp, name_t service_name, mach_port_t *sp);
 291
 292 /*
 293  * bootstrap_check_in()
 294  *
 295  * Returns the receive right for the service named by service_name. The
 296  * service must have been declared in the launchd.plist(5) file associated
 297  * with the job.  Attempts to check_in a service which is already active
 298  * are not allowed.
 299  *
 300  * If the service was declared as being associated with a server, the
 301  * check_in must come from the server's privileged port (server_port).
 302  *
 303  * Errors:      Returns appropriate kernel errors on rpc failure.
 304  *              Returns BOOTSTRAP_UNKNOWN_SERVICE, if service does not exist.
 305  *              Returns BOOTSTRAP_NOT_PRIVILEGED, if request directed to
 306  *                      bootstrap port without privilege.
 307  *              Returns BOOTSTRAP_SERVICE_ACTIVE, if service has already been
 308  *                      registered or checked-in.
 309  */
 310 kern_return_t bootstrap_check_in(
 311                 mach_port_t bp,
 312                 const name_t service_name,
 313                 mach_port_t *sp);
 314
 315 /*
 316  * bootstrap_look_up()
 317  *
 318  * Returns a send right for the service port declared/registered under the
 319  * name service_name. The service is not guaranteed to be active.  Use the
 320  * bootstrap_status call to determine the status of the service.
 321  *
 322  * Errors:      Returns appropriate kernel errors on rpc failure.
 323  *              Returns BOOTSTRAP_UNKNOWN_SERVICE, if service does not exist.
 324  */
 325 kern_return_t bootstrap_look_up(
 326                 mach_port_t bp,
 327                 const name_t service_name,
 328                 mach_port_t *sp);
 329
 330 /*
 331  * bootstrap_status()
 332  *
 333  * In practice, this call was used to preflight whether the following two
 334  * APIs would succeed.
 335  *
 336  * bootstrap_look_up()
 337  * bootstrap_check_in()
 338  *
 339  * Please don't bother. Just call the above two APIs directly and check
 340  * for failure.
 341  */
 342 kern_return_t bootstrap_status(
 343                 mach_port_t bp,
 344                 name_t service_name,
 345                 bootstrap_status_t *service_active)
 346                 AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_5;
 347
 348 /* bootstrap_strerror()
 349  *
 350  * Translate a return value from the bootstrap_*() APIs to a string.
 351  */
 352 const char *bootstrap_strerror(kern_return_t r) __attribute__((__nothrow__, __pure__, __warn_unused_result__));
 353
 354 #pragma GCC visibility pop
 355
 356 __END_DECLS
 357
 358 #endif /* __BOOTSTRAP_H__ */