system_cmds-230.tar.gz

[apple/system_cmds.git] / mach_init.tproj / mach_init.8

diff --git a/mach_init.tproj/mach_init.8 b/mach_init.tproj/mach_init.8
new file mode 100644 (file)
index 0000000..84694cd
--- /dev/null
+++ b/mach_init.tproj/mach_init.8
@@ -0,0 +1,100 @@
+.\" Copyright (c) 2002, Apple Computer, Inc.  All rights reserved.
+.\"
+.Dd March 20, 2002
+.Dt MACH_INIT 8
+.Os "Mac OS X"
+.Sh NAME
+.Nm mach_init
+.Nd Mach service naming (bootstrap) daemon
+.Sh SYNOPSIS
+.Nm mach_init
+.Op Fl D
+.Op Fl d
+.Op Fl F
+.Op Fl r Ar name-in-existing-server
+.Sh DESCRIPTION
+.Nm mach_init
+is a daemon that maintains various mappings between service names and
+the Mach ports that provide access to those services.  Clients of mach_init
+can register and lookup services, create new mapping subsets, and
+associate services with declared servers.  The mach_init daemon will
+also be responsible for launching (and/or re-launching) those service
+providing servers when attempts to use one or more of the associated services
+is detected.
+.Pp
+The options are as follows:
+.Bl -tag -width Ds
+.It Fl D
+When the
+.Fl D
+option is specified,
+.Nm mach_init
+starts in normal (non-debug) mode.  This is the default.
+.It Fl d
+When the
+.Fl d
+option is specified,
+.Nm mach_init
+starts in debug mode.
+.It Fl F
+When the
+.Fl F
+option is specified,
+.Nm mach_init
+forks during initialization so that it doesn't have to be put in
+the background manually by the caller.
+.It Fl r
+Using the
+.Fl r
+option tells
+.Nm mach_init
+to register itself in a previously running copy of
+.Nm mach_init
+under the service name
+.Ar name-in-existing-server.
+This is most useful when debugging new instances of
+.Nm mach_init
+itself, but can also be used for robustness or to allow the subsequent
+.Nm mach_init
+processes to run as a non-root user.  As mach_init is often used to
+launch servers, this could be more secure.  However, 
+.Nm mach_init
+will not allow a server declaration to specify a user id different
+than that of the requesting client (unless the client is running as root).
+So it shouldn't be required for a secure configuration.
+.El
+.Pp
+Access to
+.Nm mach_init 
+is provided through the bootstrap series of RPC APIs
+over service ports published by mach_init itself. Each Mach task has
+an assigned bootstrap port retrieved via task_get_bootstrap_port().
+These bootstrap port registrations are inherited across fork().
+.Pp
+The service registrations are grouped into subsets, providing a level
+of security. Only processes with access to the subset's bootstrap port
+will be able to register/lookup Mach ports within that subset.  Lookups
+from within a subset will search the subset first, then move on to its
+parent, and then its grand-parent, etc... until a string name match is
+found or the top of the bootstrap tree is reached.  Subsets are sometimes
+associated with login sessions to protect session-specific ports from being
+exposed outside the session.
+.Pp
+The first instance of
+.Nm mach_init
+is responsible for launching the traditional BSD process control initialization
+daemon (/sbin/init).
+.Sh SAMPLE USAGE
+.Pp
+mach_init -d -r com.company.bootstrap
+.Pp
+.Nm mach_init
+will start in debug mode, and register itself in an already running
+instance of
+.Nm mach_init
+under the service name com.company.bootstrap.
+.Sh NOTE
+.Pp
+Sending a SIGHUP to a running mach_init will toggle debug mode.
+.Sh SEE ALSO
+.Xr init 8