xref: /titanic_41/usr/src/lib/libinstzones/common/instzones_lib.h (revision 7484d118eeb19c6c9d97e3efb0d63d59a9c4153b)
1 /*
2  * CDDL HEADER START
3  *
4  * The contents of this file are subject to the terms of the
5  * Common Development and Distribution License (the "License").
6  * You may not use this file except in compliance with the License.
7  *
8  * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
9  * or http://www.opensolaris.org/os/licensing.
10  * See the License for the specific language governing permissions
11  * and limitations under the License.
12  *
13  * When distributing Covered Code, include this CDDL HEADER in each
14  * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
15  * If applicable, add the following below this CDDL HEADER, with the
16  * fields enclosed by brackets "[]" replaced with your own identifying
17  * information: Portions Copyright [yyyy] [name of copyright owner]
18  *
19  * CDDL HEADER END
20  */
21 /*
22  * Copyright (c) 2009, 2010, Oracle and/or its affiliates. All rights reserved.
23  */
24 
25 
26 
27 #ifndef _INSTZONES_LIB_H
28 #define	_INSTZONES_LIB_H
29 
30 
31 /*
32  * Module:	instzones_lib.h
33  * Group:	libinstzones
34  * Description:	This module contains the libinstzones internal data structures,
35  *		constants, and function prototypes. This include should not be
36  *		needed by any external code (consumers of this library).
37  */
38 
39 /*
40  * required includes
41  */
42 
43 /* System includes */
44 
45 #include <zone.h>
46 #include <libzonecfg.h>
47 #include <libcontract.h>
48 #include <instzones_api.h>
49 
50 
51 
52 /*
53  * C++ prefix
54  */
55 
56 #ifdef __cplusplus
57 extern "C" {
58 #endif
59 
60 /* constants */
61 
62 
63 /* macros */
64 
65 /*
66  * argument array processing type
67  */
68 
69 /*
70  * This is the "argument array" definition that is returned by _z_new_args
71  * and is used by _z_add_args, _z_free_args, etc.
72  */
73 
74 struct _argArray_t {
75 	long	_aaNumArgs;	/* number of arguments set */
76 	long	_aaMaxArgs;	/* number of arguments allocated */
77 	char	**_aaArgs;	/* actual arguments */
78 };
79 
80 typedef struct _argArray_t argArray_t;
81 
82 /*
83  * lock objects
84  */
85 
86 /*
87  * this allows a root path to be prepended to a lock object; e.g.
88  *   rootpath.%s/zone.%s/...
89  */
90 #define	LOBJ_ROOTPATH	"rootpath.%s"
91 
92 /* this locks a single zone (zone.name) */
93 #define	LOBJ_ONE_ZONE	"zone.%s"
94 
95 /* this locks all zones */
96 #define	LOBJ_ZONEADMIN	"zone.*"
97 
98 /* this locks all packages, in all zones */
99 #define	LOBJ_PKGADMIN	"zone.*/package.*"
100 
101 /* this locks all patches, in all zones */
102 #define	LOBJ_PATCHADMIN	"zone.*/patch.*"
103 
104 #define	LOCK_OBJECT_MAXLEN	512
105 #define	LOCK_KEY_MAXLEN		37
106 
107 /* paths to commands executed by this module */
108 
109 #define	PKGADM_CMD	"/usr/bin/pkgadm"
110 #define	ZONEADM_CMD	"/usr/sbin/zoneadm"
111 
112 /* max message size for program output functions (echo, echo debug, progerr) */
113 
114 #define	MAX_MESSAGE_SIZE	4096
115 
116 /* maximum number of retries when waiting for lock */
117 
118 #define	MAX_RETRIES	300
119 
120 /* delay (in seconds) between retries when waiting for lock */
121 
122 #define	RETRY_DELAY_SECS	1
123 
124 /* Size of buffer increments when reading from pipe */
125 
126 #define	PIPE_BUFFER_INCREMENT	256
127 
128 /* Maximum number of arguments to pkg_ExecCmdList */
129 
130 #define	MAX_EXEC_CMD_ARGS	100
131 
132 /*
133  * These dynamic libraries are required in order to use the zones
134  * functionality - if these libraries are not available at runtime,
135  * then zones are assumed to NOT be available, and it is assumed that
136  * the program is running in the global zone with no non-global zones.
137  */
138 
139 #if	defined(LIBZONECFG_PATH)
140 #define	ZONECFG1_LIBRARY	LIBZONECFG_PATH
141 #else	/* defined(LIBZONECFG_PATH) */
142 #define	ZONECFG1_LIBRARY	"libzonecfg.so.1"
143 #endif	/* defined(LIBZONECFG_PATH) */
144 
145 #define	ZONECFG_LIBRARY		"libzonecfg.so"
146 
147 #define	CONTRACT1_LIBRARY	"libcontract.so.1"
148 #define	CONTRACT_LIBRARY	"libcontract.so"
149 
150 /*
151  * Environment values used when running commands within a non-global zone
152  */
153 
154 /* SHELL= */
155 
156 #define	ZONE_FAILSAFESHELL	"/sbin/sh"
157 
158 /* PATH= */
159 
160 #define	ZONE_DEF_PATH		"/usr/sbin:/usr/bin"
161 
162 /* error codes */
163 #define	ERR_MALLOC_FAIL		-50
164 
165 /*
166  * zone brand list structure
167  */
168 
169 struct _zoneBrandList {
170 	char			*string_ptr;
171 	struct _zoneBrandList	*next;
172 };
173 
174 /*
175  * zone status structure - used to retrieve and hold status of zones
176  */
177 
178 typedef unsigned long _zone_status_t;
179 
180 struct _zoneListElement_t {
181 	char		*_zlName;
182 	char		*_zlPath;
183 	char		*_zlScratchName;
184 	char		*_zlLockObjects;
185 	/*
186 	 * the install "state" refers to the zone states listed in
187 	 * /usr/include/libzonecfg.h that is stored in the zone_state_t
188 	 * structure and returned from getzoneent_private() - such as:
189 	 * ZONE_STATE_CONFIGURED, ZONE_STATE_INCOMPLETE,
190 	 * ZONE_STATE_INSTALLED, ZONE_STATE_READY, ZONE_STATE_MOUNTED,
191 	 * ZONE_STATE_SHUTTING_DOWN, ZONE_STATE_DOWN.
192 	 */
193 	zone_state_t	_zlOrigInstallState;
194 	zone_state_t	_zlCurrInstallState;
195 	/*
196 	 * the kernel "status" refers to the zone status listed in
197 	 * /usr/include/sys/zone.h, returned by zone_get_state(),
198 	 * and defined in the zone_status_t enum - such as:
199 	 * ZONE_IS_UNINITIALIZED, ZONE_IS_READY, ZONE_IS_BOOTING,
200 	 * ZONE_IS_RUNNING, ZONE_IS_SHUTTING_DOWN, ZONE_IS_EMPTY,
201 	 * ZONE_IS_DOWN, ZONE_IS_DYING, ZONE_IS_DEAD.
202 	 */
203 	zone_status_t	_zlOrigKernelStatus;
204 	zone_status_t	_zlCurrKernelStatus;
205 	/*
206 	 * this is an internal state recorded about the zone (ZSF_xxx).
207 	 */
208 	_zone_status_t	_zlStatus;
209 };
210 
211 typedef struct _zoneListElement_t zoneListElement_t;
212 
213 /* bits used in the _zoneListElement _zlStatus variable */
214 
215 #define	ZST_NOT_BOOTABLE	((_zone_status_t)0x00000001)
216 #define	ZST_LOCKED		((_zone_status_t)0x00000002)
217 
218 /*
219  * User-specified list of zones.
220  */
221 
222 typedef struct zone_spec_s {
223 	struct zone_spec_s	*zl_next;
224 	boolean_t		zl_used;
225 	char			zl_name[ZONENAME_MAX];
226 } zone_spec_t;
227 
228 /*
229  * The global data structure used to hold all of the global (extern) data
230  * used by this library.
231  *
232  * --> THESE DEFINITIONS ARE ORDER DEPENDENT BASED <--
233  * --> ON THE ORDER OF THE STRUCTURE INITIALIZERS! <--
234  */
235 
236 struct _z_global_data_t {
237 	char		*_z_ObjectLocks;	/* object locks held */
238 	char 		*_z_root_dir;		/* root for zone lib fctns */
239 	int		_z_SigReceived;		/* received signal count */
240 	pid_t		_z_ChildProcessId;	/* child to propagate sigs to */
241 	zone_spec_t	*_zone_spec;		/* zones to operate on */
242 	_z_printf_fcn_t	_z_echo;		/* operational message fcn */
243 	_z_printf_fcn_t	_z_echo_debug;		/* debug message fcn */
244 	_z_printf_fcn_t	_z_progerr;		/* program error fcn */
245 };
246 
247 typedef struct _z_global_data_t z_global_data_t;
248 
249 /*
250  * When _INSTZONES_LIB_Z_DEFINE_GLOBAL_DATA is defined,
251  * instzones_lib.h will define the z_global_data structure.
252  * Otherwise an extern to the structure is inserted.
253  *
254  * --> THESE DEFINITIONS ARE ORDER DEPENDENT BASED ON <--
255  * --> THE ORDER OF THE _z_global_data_t STRUCTURE!!! <--
256  */
257 
258 #if	defined(_INSTZONES_LIB_Z_DEFINE_GLOBAL_DATA)
259 
260 /* define and initialize structure */
261 
262 z_global_data_t _z_global_data = {
263 	NULL,	/* *_z_ObjectLocks */
264 	"",	/* *_z_root_dir */
265 	0,	/* _z_SigReceived */
266 	-1,	/* _z_ChildProcessId */
267 	NULL,	/* *_zone_spec */
268 	NULL,	/* _z_echo */
269 	NULL,	/* _z_echo_debug */
270 	NULL	/* _z_progerr */
271 };
272 
273 #else	/* !defined(_INSTZONES_LIB__Z_DEFINE_GLOBAL_DATA) */
274 
275 /* define structure extern */
276 
277 extern z_global_data_t _z_global_data;
278 
279 #endif	/* defined(_INSTZONES_LIB_Z_DEFINE_GLOBAL_DATA) */
280 
281 /* function prototypes */
282 
283 /*
284  *  The following functions can be used by other libs, but not
285  *  by applications.
286  */
287 
288 /* ---> zones_states.c */
289 
290 boolean_t	_z_make_zone_ready(zoneListElement_t *a_zlem);
291 boolean_t	_z_make_zone_down(zoneListElement_t *a_zlem);
292 boolean_t	_z_make_zone_running(zoneListElement_t *a_zlem);
293 int		UmountAllZones(char *mntpnt);
294 void		*_z_calloc(size_t size);
295 void		*_z_malloc(size_t size);
296 void		*_z_realloc(void *ptr, size_t size);
297 void		*_z_strdup(char *str);
298 
299 /* ---> zones_utils.c */
300 
301 /*PRINTFLIKE1*/
302 void		_z_program_error(char *fmt, ...);
303 /*PRINTFLIKE1*/
304 void		_z_echo(char *fmt, ...);
305 /*PRINTFLIKE1*/
306 void		_z_echoDebug(char *a_fmt, ...);
307 int		_z_is_directory(char *path);
308 boolean_t	_z_running_in_global_zone(void);
309 boolean_t	_z_zones_are_implemented(void);
310 void		_z_sig_trap(int a_signo);
311 int		_z_close_file_descriptors(void *a_fds, int a_fd);
312 boolean_t	_z_brands_are_implemented(void);
313 
314 
315 /* ---> zones_locks.c */
316 
317 boolean_t	_z_adjust_lock_object_for_rootpath(char **r_result,
318 			char *a_lockObject);
319 boolean_t	_z_acquire_lock(char **r_lockKey, char *a_zoneName,
320 			char *a_lock, pid_t a_pid, boolean_t a_wait);
321 boolean_t	_z_lock_zone(zoneListElement_t *a_zlst,
322 			ZLOCKS_T a_lflags);
323 boolean_t	_z_lock_zone_object(char **r_objectLocks,
324 			char *a_zoneName, char *a_lockObject,
325 			pid_t a_pid, char *a_waitingMsg,
326 			char *a_busyMsg);
327 boolean_t	_z_release_lock(char *a_zoneName, char *a_lock,
328 			char *a_key, boolean_t a_wait);
329 boolean_t	_z_unlock_zone(zoneListElement_t *a_zlst,
330 			ZLOCKS_T a_lflags);
331 boolean_t	_z_unlock_zone_object(char **r_objectLocks,
332 			char *a_zoneName, char *a_lockObject,
333 			char *a_errMsg);
334 
335 /* ---> zones_args.c */
336 
337 void		_z_free_args(argArray_t *a_args);
338 argArray_t	*_z_new_args(int initialCount);
339 /*PRINTFLIKE2*/
340 boolean_t	_z_add_arg(argArray_t *a_args, char *a_format, ...);
341 int		_z_get_argc(argArray_t *a_args);
342 char		**_z_get_argv(argArray_t *a_args);
343 
344 /* ---> zones_str.c */
345 
346 boolean_t	_z_strContainsToken(char *a_string, char *a_token,
347 			char *a_separators);
348 char		*_z_strGetToken(char *r_sep, char *a_string,
349 			int a_index, char *a_separators);
350 void		_z_strRemoveLeadingWhitespace(char **a_str);
351 void		_z_strGetToken_r(char *r_sep, char *a_string,
352 			int a_index, char *a_separators, char *a_buf,
353 			int a_bufLen);
354 void		_z_strAddToken(char **a_old, char *a_new,
355 			char a_separator);
356 void		_z_strRemoveToken(char **r_string, char *a_token,
357 			char *a_separators, int a_index);
358 /*PRINTFLIKE3*/
359 void		_z_strPrintf_r(char *a_buf, int a_bufLen,
360 			char *a_format, ...);
361 /*PRINTFLIKE1*/
362 char		*_z_strPrintf(char *a_format, ...);
363 
364 /* ---> zones_exec.c */
365 
366 int		_z_zone_exec(int *r_status, char **r_results, char *a_inputFile,
367 			char *a_path, char *a_argv[], const char *a_zoneName,
368 			int *a_fds);
369 int		_zexec(const char *a_zoneName,
370 			const char *path, char *argv[]);
371 char		*_zexec_add_env(char *name, char *value);
372 int		_zexec_init_template(void);
373 char		**_zexec_prep_env();
374 
375 /*
376  * C++ postfix
377  */
378 
379 #ifdef __cplusplus
380 }
381 #endif
382 
383 #endif	/* _INSTZONES_LIB_H */
384