[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.  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
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
	32	starts in normal (non-debug) mode. This is the default.
	33	.It Fl d
	34	When the
	35	.Fl d
	36	option is specified,
	37	.Nm mach_init
	38	starts in debug mode.
	39	.It Fl F
	40	When the
	41	.Fl F
	42	option is specified,
	43	.Nm mach_init
	44	forks during initialization so that it doesn't have to be put in
	45	the background manually by the caller.
	46	.It Fl r
	47	Using the
	48	.Fl r
	49	option tells
	50	.Nm mach_init
	51	to register itself in a previously running copy of
	52	.Nm mach_init
	53	under the service name
	54	.Ar name-in-existing-server.
	55	This is most useful when debugging new instances of
	56	.Nm mach_init
	57	itself, but can also be used for robustness or to allow the subsequent
	58	.Nm mach_init
	59	processes to run as a non-root user. As mach_init is often used to
	60	launch servers, this could be more secure. However,
	61	.Nm mach_init
	62	will not allow a server declaration to specify a user id different
	63	than that of the requesting client (unless the client is running as root).
	64	So it shouldn't be required for a secure configuration.
65	.El
66	.Pp
67	Access to
68	.Nm mach_init
69	is provided through the bootstrap series of RPC APIs
70	over service ports published by mach_init itself. Each Mach task has
71	an assigned bootstrap port retrieved via task_get_bootstrap_port().
72	These bootstrap port registrations are inherited across fork().
73	.Pp
74	The service registrations are grouped into subsets, providing a level
75	of security. Only processes with access to the subset's bootstrap port
76	will be able to register/lookup Mach ports within that subset. Lookups
77	from within a subset will search the subset first, then move on to its
78	parent, and then its grand-parent, etc... until a string name match is
79	found or the top of the bootstrap tree is reached. Subsets are sometimes
80	associated with login sessions to protect session-specific ports from being
81	exposed outside the session.
82	.Pp
83	The first instance of
84	.Nm mach_init
85	is responsible for launching the traditional BSD process control initialization
86	daemon (/sbin/init).
87	.Sh SAMPLE USAGE
88	.Pp
89	mach_init -d -r com.company.bootstrap
90	.Pp
91	.Nm mach_init
92	will start in debug mode, and register itself in an already running
93	instance of
94	.Nm mach_init
95	under the service name com.company.bootstrap.
96	.Sh NOTE
97	.Pp
98	Sending a SIGHUP to a running mach_init will toggle debug mode.
99	.Sh SEE ALSO
100	.Xr init 8