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

.\" 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.  Logging is minimal (only security-related
and process launch failures are logged).  Core dumps are disabled for launched
servers.  This is the default.
.It Fl d
When the
.Fl d
option is specified,
.Nm mach_init
starts in debug mode. Logging is extensive.  Core dumps will be taken for any
launched servers that crash.
.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
Commit	Line	Data
b51d5b5f A	1	.\" Copyright (c) 2002, Apple Computer, Inc. All rights reserved.
	2	.\"
	3	.Dd March 20, 2002
	4	.Dt MACH_INIT 8
	5	.Os "Mac OS X"
	6	.Sh NAME
	7	.Nm mach_init
	8	.Nd Mach service naming (bootstrap) daemon
	9	.Sh SYNOPSIS
	10	.Nm mach_init
	11	.Op Fl D
	12	.Op Fl d
	13	.Op Fl F
	14	.Op Fl r Ar name-in-existing-server
	15	.Sh DESCRIPTION
	16	.Nm mach_init
	17	is a daemon that maintains various mappings between service names and
	18	the Mach ports that provide access to those services. Clients of mach_init
	19	can register and lookup services, create new mapping subsets, and
	20	associate services with declared servers. The mach_init daemon will
	21	also be responsible for launching (and/or re-launching) those service
	22	providing servers when attempts to use one or more of the associated services
	23	is detected.
	24	.Pp
	25	The options are as follows:
	26	.Bl -tag -width Ds
	27	.It Fl D
	28	When the
	29	.Fl D
	30	option is specified,
	31	.Nm mach_init
20e66415 A	32	starts in normal (non-debug) mode. Logging is minimal (only security-related
	33	and process launch failures are logged). Core dumps are disabled for launched
	34	servers. This is the default.
b51d5b5f A	35	.It Fl d
	36	When the
	37	.Fl d
	38	option is specified,
	39	.Nm mach_init
20e66415 A	40	starts in debug mode. Logging is extensive. Core dumps will be taken for any
20e66415 A	41	launched servers that crash.
b51d5b5f A	42	.It Fl F
	43	When the
	44	.Fl F
	45	option is specified,
	46	.Nm mach_init
	47	forks during initialization so that it doesn't have to be put in
	48	the background manually by the caller.
	49	.It Fl r
	50	Using the
	51	.Fl r
	52	option tells
	53	.Nm mach_init
	54	to register itself in a previously running copy of
	55	.Nm mach_init
	56	under the service name
	57	.Ar name-in-existing-server.
	58	This is most useful when debugging new instances of
	59	.Nm mach_init
	60	itself, but can also be used for robustness or to allow the subsequent
	61	.Nm mach_init
	62	processes to run as a non-root user. As mach_init is often used to
	63	launch servers, this could be more secure. However,
	64	.Nm mach_init
	65	will not allow a server declaration to specify a user id different
	66	than that of the requesting client (unless the client is running as root).
	67	So it shouldn't be required for a secure configuration.
	68	.El
	69	.Pp
	70	Access to
	71	.Nm mach_init
	72	is provided through the bootstrap series of RPC APIs
	73	over service ports published by mach_init itself. Each Mach task has
	74	an assigned bootstrap port retrieved via task_get_bootstrap_port().
	75	These bootstrap port registrations are inherited across fork().
	76	.Pp
	77	The service registrations are grouped into subsets, providing a level
	78	of security. Only processes with access to the subset's bootstrap port
	79	will be able to register/lookup Mach ports within that subset. Lookups
	80	from within a subset will search the subset first, then move on to its
	81	parent, and then its grand-parent, etc... until a string name match is
	82	found or the top of the bootstrap tree is reached. Subsets are sometimes
	83	associated with login sessions to protect session-specific ports from being
	84	exposed outside the session.
	85	.Pp
	86	The first instance of
	87	.Nm mach_init
	88	is responsible for launching the traditional BSD process control initialization
	89	daemon (/sbin/init).
	90	.Sh SAMPLE USAGE
	91	.Pp
	92	mach_init -d -r com.company.bootstrap
	93	.Pp
	94	.Nm mach_init
	95	will start in debug mode, and register itself in an already running
	96	instance of
	97	.Nm mach_init
	98	under the service name com.company.bootstrap.
	99	.Sh NOTE
	100	.Pp
	101	Sending a SIGHUP to a running mach_init will toggle debug mode.
	102	.Sh SEE ALSO
	103	.Xr init 8