launchd/src/libbootstrap_public.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
 100 typedef boolean_t *bool_array_t;
 101
 102 #define BOOTSTRAP_MAX_LOOKUP_COUNT              20
 103
 104 #define BOOTSTRAP_SUCCESS                       0
 105 #define BOOTSTRAP_NOT_PRIVILEGED                1100
 106 #define BOOTSTRAP_NAME_IN_USE                   1101
 107 #define BOOTSTRAP_UNKNOWN_SERVICE               1102
 108 #define BOOTSTRAP_SERVICE_ACTIVE                1103
 109 #define BOOTSTRAP_BAD_COUNT                     1104
 110 #define BOOTSTRAP_NO_MEMORY                     1105
 111
 112 #define BOOTSTRAP_STATUS_INACTIVE               0
 113 #define BOOTSTRAP_STATUS_ACTIVE                 1
 114 #define BOOTSTRAP_STATUS_ON_DEMAND              2
 115
 116 /*
 117  * After main() starts, it is safe to assume that this variable is always set.
 118  */
 119 extern mach_port_t bootstrap_port;
 120
 121 /*
 122  * bootstrap_create_server()
 123  *
 124  * Declares a server that mach_init will re-spawn within the specified
 125  * bootstrap context.  The server is considered already "active"
 126  * (i.e. will not be re-spawned) until the returned server_port is
 127  * deallocated.
 128  *
 129  * In the meantime, services can be declared against the server,
 130  * by using the server_port as the privileged bootstrap target of
 131  * subsequent bootstrap_create_service() calls.
 132  *
 133  * When mach_init re-spawns the server, its task bootstrap port
 134  * is set to the privileged sever_port.  Through this special
 135  * bootstrap port, it can access all of parent bootstrap's context
 136  * (and all services are created in the parent's namespace). But
 137  * all additional service declarations (and declaration removals)
 138  * will be associated with this particular server.
 139  *
 140  * Only a holder of the server_port privilege bootstrap port can
 141  * check in or register over those services.
 142  *
 143  * When all services associated with a server are deleted, and the server
 144  * exits, it will automatically be deleted itself.
 145  *
 146  * If the server is declared "on_demand," then a non-running server
 147  * will be re-launched on first use of one of the service ports
 148  * registered against it.  Otherwise, it will be re-launched
 149  * immediately upon exiting (whether any client is actively using
 150  * any of the service ports or not).
 151  *
 152  * Errors:      Returns appropriate kernel errors on rpc failure.
 153  *              Returns BOOTSTRAP_NOT_PRIVILEGED, bootstrap or uid invalid.
 154  */
 155 kern_return_t bootstrap_create_server(
 156                 mach_port_t bp,
 157                 cmd_t server_cmd,
 158                 uid_t server_uid,
 159                 boolean_t on_demand,
 160                 mach_port_t *server_port);
 161
 162 /*
 163  * bootstrap_subset()
 164  *
 165  * Returns a new port to use as a bootstrap port.  This port behaves
 166  * exactly like the previous bootstrap_port, except that ports dynamically
 167  * registered via bootstrap_register() are available only to users of this
 168  * specific subset_port.  Lookups on the subset_port will return ports
 169  * registered with this port specifically, and ports registered with
 170  * ancestors of this subset_port.  Duplications of services already
 171  * registered with an ancestor port may be registered with the subset port
 172  * are allowed.  Services already advertised may then be effectively removed
 173  * by registering PORT_NULL for the service.
 174  * When it is detected that the requestor_port is destroyed the subset
 175  * port and all services advertized by it are destroyed as well.
 176  *
 177  * Errors:      Returns appropriate kernel errors on rpc failure.
 178  */
 179 kern_return_t bootstrap_subset(
 180                 mach_port_t bp,
 181                 mach_port_t requestor_port,
 182                 mach_port_t *subset_port);
 183
 184 /*
 185  * bootstrap_unprivileged()
 186  *
 187  * Given a bootstrap port, return its unprivileged equivalent.  If
 188  * the port is already unprivileged, another reference to the same
 189  * port is returned.
 190  *
 191  * This is most often used by servers, which are launched with their
 192  * bootstrap port set to the privileged port for the server, to get
 193  * an unprivileged version of the same port for use by its unprivileged
 194  * children (or any offspring that it does not want to count as part
 195  * of the "server" for mach_init registration and re-launch purposes).
 196  *
 197  * Native launchd jobs are always started with an unprivileged port.
 198  */
 199 kern_return_t bootstrap_unprivileged(
 200                 mach_port_t bp,
 201                 mach_port_t *unpriv_port)
 202                 AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_5;
 203
 204 /*
 205  * bootstrap_parent()
 206  *
 207  * Given a bootstrap subset port, return the parent bootstrap port.
 208  * If the specified bootstrap port is already the root subset,
 209  * the same port will be returned. Much like "." and ".." are the same
 210  * in the file system name space for the root directory ("/").
 211  *
 212  * Errors:
 213  *      Returns BOOTSTRAP_NOT_PRIVILEGED if the caller is not running
 214  *      with an effective user id of root (as determined by the security
 215  *      token in the message trailer).
 216  */
 217 kern_return_t bootstrap_parent(
 218                 mach_port_t bp,
 219                 mach_port_t *parent_port);
 220
 221 /*
 222  * bootstrap_register()
 223  *
 224  * Registers a send right for service_port with the service identified by
 225  * service_name.  Attempts to register a service where an active binding
 226  * already exists are rejected.
 227  *
 228  * If the service was previously declared with bootstrap_create_service(),
 229  * but is not currently active, this call can be used to undeclare the
 230  * service. The bootstrap port used must have sufficient privilege to
 231  * do so.  (Registering MACH_PORT_NULL is especially useful for shutting
 232  * down declared services).
 233  *
 234  * This API is deprecated. Old scenarios and recommendations:
 235  *
 236  * 1) If the code was registering a well known name, please switch to launchd.
 237  *
 238  * 2) If the code was registering a dynamically generated string and passing
 239  *    the string to other applications, please rewrite the code to send a Mach
 240  *    send-right directly.
 241  *
 242  * 3) If the launchd job maintained an optional Mach service, please reserve
 243  *    the name with launchd and control the presense of the service through
 244  *    ownership of the Mach receive right like so.
 245  *
 246  *      <key>MachServices</key>
 247  *      <dict>
 248  *              <key>com.apple.windowserver</key>
 249  *              <true/>
 250  *              <key>com.apple.windowserver.active</key>
 251  *              <dict>
 252  *                      <key>HideUntilCheckIn</key>
 253  *                      <true/>
 254  *              </dict>
 255  *      </dict>
 256  *
 257  *
 258  * Errors:      Returns appropriate kernel errors on rpc failure.
 259  *              Returns BOOTSTRAP_NOT_PRIVILEGED, if request directed to
 260  *                      bootstrap port without privilege.
 261  *              Returns BOOTSTRAP_NAME_IN_USE, if service has already been
 262  *                      register or checked-in.
 263  */
 264 kern_return_t bootstrap_register(
 265                 mach_port_t bp,
 266                 name_t service_name,
 267                 mach_port_t sp)
 268                 AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_5;
 269
 270 /*
 271  * bootstrap_create_service()
 272  *
 273  * Creates a service named "service_name" and returns send rights to that
 274  * port in "service_port."  The port may later be checked in as if this
 275  * port were configured in the bootstrap configuration file.
 276  *
 277  * Errors:      Returns appropriate kernel errors on rpc failure.
 278  *              Returns BOOTSTRAP_SERVICE_ACTIVE, if service already exists.
 279  */
 280 kern_return_t bootstrap_create_service(
 281                 mach_port_t bp,
 282                 name_t service_name,
 283                 mach_port_t *sp);
 284
 285 /*
 286  * bootstrap_check_in()
 287  *
 288  * Returns the receive right for the service named by service_name. The
 289  * service must have previously been declared in this bootstrap context via
 290  * a call to bootstrap_create_service().  Attempts to check_in a service
 291  * which is already active are not allowed.
 292  *
 293  * If the service was declared as being associated with a server, the
 294  * check_in must come from the server's privileged port (server_port).
 295  *
 296  * Errors:      Returns appropriate kernel errors on rpc failure.
 297  *              Returns BOOTSTRAP_UNKNOWN_SERVICE, if service does not exist.
 298  *              Returns BOOTSTRAP_NOT_PRIVILEGED, if request directed to
 299  *                      bootstrap port without privilege.
 300  *              Returns BOOTSTRAP_SERVICE_ACTIVE, if service has already been
 301  *                      registered or checked-in.
 302  */
 303 kern_return_t bootstrap_check_in(
 304                 mach_port_t bp,
 305                 name_t service_name,
 306                 mach_port_t *sp);
 307
 308 /*
 309  * bootstrap_look_up()
 310  *
 311  * Returns a send right for the service port declared/registered under the
 312  * name service_name. The service is not guaranteed to be active.  Use the
 313  * bootstrap_status call to determine the status of the service.
 314  *
 315  * Errors:      Returns appropriate kernel errors on rpc failure.
 316  *              Returns BOOTSTRAP_UNKNOWN_SERVICE, if service does not exist.
 317  */
 318 kern_return_t bootstrap_look_up(
 319                 mach_port_t bp,
 320                 name_t service_name,
 321                 mach_port_t *sp);
 322
 323 /*
 324  * bootstrap_status()
 325  *
 326  * In practice, this call was used to preflight whether the following two
 327  * APIs would succeed.
 328  *
 329  * bootstrap_look_up()
 330  * bootstrap_check_in()
 331  *
 332  * Please don't bother. Just call the above two APIs directly and check
 333  * for failure.
 334  */
 335 kern_return_t bootstrap_status(
 336                 mach_port_t bp,
 337                 name_t service_name,
 338                 bootstrap_status_t *service_active)
 339                 AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_5;
 340
 341 /* bootstrap_strerror()
 342  *
 343  * Translate a return value from the bootstrap_*() APIs to a string.
 344  */
 345 const char *bootstrap_strerror(kern_return_t r) __attribute__((__nothrow__, __pure__, __warn_unused_result__));
 346
 347 #pragma GCC visibility pop
 348
 349 __END_DECLS
 350
 351 #endif