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