Print this page
OS-5642 containerbuddy unable to fork while using syslog driver, causing container services to hang
Reviewed by: Patrick Mooney <patrick.mooney@joyent.com>
Reviewed by: Robert Mustacchi <rm@joyent.com>
Approved by: Patrick Mooney <patrick.mooney@joyent.com>
OS-4818 contract template disappears on exec
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man4/process.4.man.txt
+++ new/usr/src/man/man4/process.4.man.txt
1 1 PROCESS(4) File Formats and Configurations PROCESS(4)
2 2
3 3
4 4
5 5 NAME
6 6 process - process contract type
7 7
8 8 SYNOPSIS
9 9 /system/contract/process
10 10
11 11
12 12 DESCRIPTION
13 13 Process contracts allow processes to create a fault boundary around a
14 14 set of subprocesses and observe events which occur within that
15 15 boundary.
16 16
17 17
18 18 Process contracts are managed using the contract(4) file system and the
19 19 libcontract(3LIB) library. The process contract type directory is
20 20 /system/contract/process.
21 21
22 22 CREATION
23 23 A process contract is created when an LWP that has an active process
24 24 contract template calls fork(2). Initially, the child process created
25 25 by fork() is the only resource managed by the contract. When an LWP
26 26 that does not have an active process contract template calls fork(),
27 27 the child process created by fork() is added as a resource to the
28 28 process contract of which the parent was a member.
29 29
30 30 EVENT TYPES
31 31 The following events types are defined:
32 32
33 33 CT_PR_EV_EMPTY
34 34
35 35 The last member of the process contract exited.
36 36
37 37
38 38 CT_PR_EV_FORK
39 39
40 40 A new process has been added to the process contract.
41 41
42 42
43 43 CT_PR_EV_EXIT
44 44
45 45 A member of the process contract exited.
46 46
47 47
48 48 CT_PR_EV_CORE
49 49
50 50 A process failed and dumped core. This could also occur if the
51 51 process would have dumped core had appropriate coreadm(1M) options
52 52 been enabled and core file size was unlimited.
53 53
54 54
55 55 CT_PR_EV_SIGNAL
56 56
57 57 A process received a fatal signal from a process, other than the
58 58 owner of the process contract, that is a member of a different
59 59 process contract.
60 60
61 61
62 62 CT_PR_EV_HWERR
63 63
64 64 A process was killed because of an uncorrectable hardware error.
65 65
66 66
67 67 TERMS
68 68 The following common contract terms, defined in contract(4), have
69 69 process-contract specific attributes:
70 70
71 71 critical event set
72 72
73 73 The default value for the critical event set is (CT_PR_EV_EMPTY |
74 74 CT_PR_EV_HWERR).
75 75
76 76 An attempt by a user without the {PRIV_CONTRACT_EVENT} privilege in
77 77 its effective set to add an event, other than CT_PR_EV_EMPTY, to
78 78 the critical event set which is not present in the fatal set, or if
79 79 the CT_PR_PGONLY parameter is set and the same user attempts to add
80 80 any event, other than CT_PR_EV_EMPTY, to the critical event set,
81 81 fails.
82 82
83 83
84 84 informative event set
85 85
86 86 The default value for the informative event set is (CT_PR_EV_CORE |
87 87 CT_PR_EV_SIGNAL).
88 88
89 89
90 90
91 91 The following contract terms can be read from or written to a process
92 92 contract template using the named libcontract(3LIB) interfaces. These
93 93 contract terms are in addition to those described in contract(4).
94 94
95 95 creator's aux
96 96
97 97 Auxiliary contract description. The purpose of this field is to
98 98 provide the contract creator with a way to differentiate process
99 99 contracts it creates under the same service FMRI. Use
100 100 ct_pr_tmpl_set_svc_aux(3CONTRACT) to set this term. The default
101 101 value is an empty string. The contents of this field should be
102 102 limited to 7-bit ASCII values.
103 103
104 104
105 105 fatal event set
106 106
107 107 Defines a set of events which, when generated, causes all members
108 108 of the process contract to be killed with SIGKILL, or the
109 109 intersection of the contract and the containing process group if
110 110 the CT_PR_PGRPONLY parameter is set. Set this term with
111 111 ct_pr_tmpl_set_fatal(3CONTRACT). The fatal event set is restricted
112 112 to CT_PR_EV_CORE, CT_PR_EV_SIGNAL, and CT_PR_EV_HWERR. For
113 113 CT_PR_EV_CORE and CT_PR_EV_SIGNAL events, the scope of SIGKILL is
114 114 limited to those processes which the contract author or the event
115 115 source could have normally sent signals to.
116 116
117 117 The default value for the fatal event set is CT_PR_EV_HWERR.
118 118
119 119 If a user without the {PRIV_CONTRACT_EVENT} privilege in its
120 120 effective set removes an event from the fatal event set which is
121 121 present in the critical event set, the corresponding event is
122 122 automatically removed from the critical event set and added to the
123 123 informative event set.
124 124
125 125
126 126 parameter set
127 127
128 128 Defines miscellaneous other settings. Use
129 129 ct_pr_tmpl_set_param(3CONTRACT) to set this term.
130 130
131 131 The default parameter set is empty.
132 132
133 133 The value is a bit vector comprised of some or all of:
134 134
135 135 CT_PR_INHERIT
|
↓ open down ↓ |
135 lines elided |
↑ open up ↑ |
136 136
137 137 If set, indicates that the process contract is to be inherited
138 138 by the process contract the contract owner is a member of if
139 139 the contract owner exits before explicitly abandoning the
140 140 process contract.
141 141
142 142 If not set, the process contract is automatically abandoned
143 143 when the owner exits.
144 144
145 145
146 + CT_PR_KEEP_EXEC
147 +
148 + If set, the process contract template remains active across
149 + exec(2). This can be used to setup a contract for children of
150 + an application which is not contract-aware. If this is not set
151 + then the system clears the active template when the process
152 + execs. Because this option is intended for an application which
153 + is not contract-aware, new child process contracts will be
154 + automatically abandoned by the parent.
155 +
156 +
146 157 CT_PR_NOORPHAN
147 158
148 159 If set, all processes in a process contract are sent SIGKILL if
149 160 the process contract is abandoned, either explicitly or because
150 161 the holder died and CT_PR_INHERIT was not set. The scope of
151 162 SIGKILL is limited to those processes which the contract author
152 163 or the event source could have normally sent signals to.
153 164
154 165 If this is not set and the process contract is abandoned, the
155 166 process contract is orphaned, that is, continues to exist
156 167 without owner.
157 168
158 169
159 170 CT_PR_PGRPONLY
160 171
161 172 If set, only those processes within the same process group and
162 173 process contract as a fatal error-generating process are
163 174 killed.
164 175
165 176 If not set, all processes within the process contract are
166 177 killed if a member process encounters an error specified in the
167 178 fatal set.
168 179
169 180 If a user without the {PRIV_CONTRACT_EVENT} privilege in its
170 181 effective set adds CT_PR_PGRPONLY to a template's parameter
171 182 set, any events other than CT_PR_EV_EMPTY are automatically
172 183 removed from the critical event set and added to the
173 184 informative event set.
174 185
175 186
176 187 CT_PR_REGENT
177 188
178 189 If set, the process contract can inherit unabandoned contracts
179 190 left by exiting member processes.
180 191
181 192 If not set, indicates that the process contract should not
182 193 inherit contracts from member processes. If a process exits
183 194 before abandoning a contract it owns and is a member of a
184 195 process contract which does not have CT_PR_REGENT set, the
185 196 system automatically abandons the contract.
186 197
187 198 If a regent process contract has inherited contracts and is
188 199 abandoned by its owner, its inherited contracts are abandoned.
189 200
190 201
191 202
192 203 service FMRI
193 204
194 205 Specifies the service FMRI associated with the process contract.
195 206 Use ct_pr_tmpl_set_svc_fmri(3CONTRACT) to set this term. The
196 207 default is to inherit the value from the creator's process
197 208 contract. When this term is uninitialized,
198 209 ct_pr_tmpl_get_svc_fmri(3CONTRACT) returns the token string
199 210 inherited: to indicate the value has not been set and is inherited.
200 211 Setting the service FMRI to inherited: clears the current (B value
201 212 and the term is inherited from the creator's process contract. To
202 213 set this term a process must have {PRIV_CONTRACT_IDENTITY} in its
203 214 effective set.
204 215
205 216
206 217 transfer contract
207 218
208 219 Specifies the ID of an empty process contract held by the caller
209 220 whose inherited process contracts are to be transferred to the
210 221 newly created contract. Use ct_pr_tmpl_set_transfer(3CONTRACT) to
211 222 set the tranfer contract. Attempts to specify a contract not held
212 223 by the calling process, or a contract which still has processes in
213 224 it, fail.
214 225
215 226 The default transfer term is 0, that is, no contract.
216 227
217 228
218 229 STATUS
219 230 In addition to the standard items, the status object read from a status
220 231 file descriptor contains the following items to obtain this information
221 232 respectively:
222 233
223 234 service contract ID
224 235
225 236 Specifies the process contract id which defined the service FMRI
226 237 term. Use ct_pr_status_get_svc_ctid(3CONTRACT) to read the term's
227 238 value. It can be used to determine if the service FMRI was
228 239 inherited as in the example below.
229 240
230 241 ctid_t ctid; /* our contract id */
231 242 int fd; /* fd of ctid's status file */
232 243
233 244 ct_stathdl_(Bt status;
234 245 ctid_t svc_ctid;
235 246
236 247 if (ct_status_read(fd, CTD_FIXED, &status) == 0) {
237 248 if (ct_pr_status_get_svc_ctid(status, &svc_ctid) == 0) {
238 249 if (svc_ctid == ctid)
239 250 /* not inherited */
240 251 else
241 252 /* inherited */
242 253 }
243 254 ct_status_free(status);
244 255 }
245 256
246 257
247 258
248 259
249 260
250 261 If CTD_ALL is specified, the following items are also available:
251 262
252 263 Member list
253 264
254 265 The PIDs of processes which are members of the process contract.
255 266 Use ct_pr_status_get_members(3CONTRACT) for this information.
256 267
257 268
258 269 Inherited contract list
259 270
260 271 The IDs of contracts which have been inherited by the process
261 272 contract. Use ct_pr_status_get_contracts(3CONTRACT) to obtain this
262 273 information.
263 274
264 275
265 276 Service FMRI (term)
266 277
267 278 Values equal to the terms used when the contract was written. The
268 279 Service FMRI term of the process contract of a process en(Btering a
269 280 zone has the value svc:/system/zone_enter:default when read from
270 281 the non-global zone.
271 282
272 283
273 284 contract creator
274 285
275 286 Specifies the process that created the process contract. Use
276 287 ct_pr_status_get_svc_creator(3CONTRACT) to read the term's value.
277 288
278 289
279 290 creator's aux (term)
280 291
281 292 Values equal to the terms used when the contract was written.
282 293
283 294
284 295
285 296 The following standard status items have different meanings in some
286 297 situations:
287 298
288 299 Ownership state
289 300
290 301 If the process contract has a state of CTS_OWNED or CTS_INHERITED
291 302 and is held by an entity in the global zone, but contains processes
292 303 in a non-global zone, it appears to have the state CTS_OWNED when
293 304 observed by processes in the non-global zone.
294 305
295 306
296 307 Contract holder
297 308
298 309 If the process contract has a state of CTS_OWNED or CTS_INHERITED
299 310 and is held by an entity in the global zone, but contains processes
300 311 in a non-global zone, it appears to be held by the non-global
301 312 zone's zsched when observed by processes in the non-global zone.
302 313
303 314
304 315 EVENTS
305 316 In addition to the standard items, an event generated by a process
306 317 contract contains the following information:
307 318
308 319 Generating PID
309 320
310 321 The process ID of the member process which experienced the event,
311 322 or caused the contract event to be generated (in the case of
312 323 CT_PR_EV_EMPTY). Use ct_pr_event_get_pid(3CONTRACT) to obtain this
313 324 information.
314 325
315 326
316 327
317 328 If the event type is CT_PR_EV_FORK, the event contains:
318 329
319 330 Parent PID
320 331
321 332 The process ID which forked [Generating PID]. Use
322 333 ct_pr_event_get_ppid(3CONTRACT) to obtain this information.
323 334
324 335
325 336
326 337 If the event type is CT_PR_EV_EXIT, the event contains:
327 338
328 339 Exit status
329 340
330 341 The exit status of the process. Use
331 342 ct_pr_event_get_exitstatus(3CONTRACT) to obtain this information.
332 343
333 344
334 345
335 346 If the event type is CT_PR_EV_CORE, the event can contain:
336 347
337 348 Process core name
338 349
339 350 The name of the per-process core file. Use
340 351 ct_pr_event_get_pcorefile(3CONTRACT) to obtain this information.
341 352
342 353
343 354 Global core name
344 355
345 356 The name of the process's zone's global core file. Use
346 357 ct_pr_event_get_gcorefile(3CONTRACT) to obtain this information.
347 358
348 359
349 360 Zone core name
350 361
351 362 The name of the system-wide core file in the global zone. Use
352 363 ct_pr_event_get_zcorefile(3CONTRACT) to obtain this information.
353 364
354 365
355 366
356 367 See coreadm(1M) for more information about per-process, global, and
357 368 system-wide core files.
358 369
359 370
360 371 If the event type is CT_PR_EV_SIGNAL, the event contains:
361 372
362 373 Signal
363 374
364 375 The number of the signal which killed the process. Use
365 376 ct_pr_event_get_signal(3CONTRACT) to obtain this information.
366 377
367 378
368 379
369 380 It can contain:
370 381
371 382 sender
372 383
373 384 The PID of the process which sent the signal. Use
374 385 ct_pr_event_get_sender(3CONTRACT) to obtain this information.
375 386
376 387
377 388 FILES
378 389 /usr/include/sys/contract/process.h
379 390
380 391 Contains definitions of event-type macros.
381 392
382 393
383 394 SEE ALSO
384 395 ctrun(1), ctstat(1), ctwatch(1), coreadm(1M), close(2), fork(2),
385 396 ioctl(2), open(2), poll(2), ct_pr_event_get_exitstatus(3CONTRACT),
386 397 ct_pr_event_get_gcorefile(3CONTRACT),
387 398 ct_pr_event_get_pcorefile(3CONTRACT), ct_pr_event_get_pid(3CONTRACT),
388 399 ct_pr_event_get_ppid(3CONTRACT), ct_pr_event_get_signal(3CONTRACT),
|
↓ open down ↓ |
233 lines elided |
↑ open up ↑ |
389 400 ct_pr_event_get_zcorefile(3CONTRACT),
390 401 ct_pr_status_get_contracts(3CONTRACT),
391 402 ct_pr_status_get_members(3CONTRACT), ct_pr_status_get_param(3CONTRACT),
392 403 ct_pr_tmpl_set_fatal(3CONTRACT), ct_pr_tmpl_set_param(3CONTRACT),
393 404 ct_pr_tmpl_set_transfer(3CONTRACT), ct_tmpl_set_cookie(3CONTRACT),
394 405 ct_tmpl_set_critical(3CONTRACT), ct_tmpl_set_informative(3CONTRACT),
395 406 libcontract(3LIB), contract(4), privileges(5)
396 407
397 408
398 409
399 - March 25, 2008 PROCESS(4)
410 + Sept 6, 2016 PROCESS(4)
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX