xref: /titanic_41/usr/src/lib/libinstzones/common/instzones_lib.h (revision 4656d4747c8743290bfbe910c64cd75eb4e4af8d)
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 #define	LOCK_OBJECT_MAXLEN	512
102 #define	LOCK_KEY_MAXLEN		37
103 
104 /* paths to commands executed by this module */
105 
106 #define	PKGADM_CMD	"/usr/bin/pkgadm"
107 #define	ZONEADM_CMD	"/usr/sbin/zoneadm"
108 
109 /* max message size for program output functions (echo, echo debug, progerr) */
110 
111 #define	MAX_MESSAGE_SIZE	4096
112 
113 /* maximum number of retries when waiting for lock */
114 
115 #define	MAX_RETRIES	300
116 
117 /* delay (in seconds) between retries when waiting for lock */
118 
119 #define	RETRY_DELAY_SECS	1
120 
121 /* Size of buffer increments when reading from pipe */
122 
123 #define	PIPE_BUFFER_INCREMENT	256
124 
125 /* Maximum number of arguments to pkg_ExecCmdList */
126 
127 #define	MAX_EXEC_CMD_ARGS	100
128 
129 /*
130  * These dynamic libraries are required in order to use the zones
131  * functionality - if these libraries are not available at runtime,
132  * then zones are assumed to NOT be available, and it is assumed that
133  * the program is running in the global zone with no non-global zones.
134  */
135 
136 #if	defined(LIBZONECFG_PATH)
137 #define	ZONECFG1_LIBRARY	LIBZONECFG_PATH
138 #else	/* defined(LIBZONECFG_PATH) */
139 #define	ZONECFG1_LIBRARY	"libzonecfg.so.1"
140 #endif	/* defined(LIBZONECFG_PATH) */
141 
142 #define	ZONECFG_LIBRARY		"libzonecfg.so"
143 
144 #define	CONTRACT1_LIBRARY	"libcontract.so.1"
145 #define	CONTRACT_LIBRARY	"libcontract.so"
146 
147 /*
148  * Environment values used when running commands within a non-global zone
149  */
150 
151 /* SHELL= */
152 
153 #define	ZONE_FAILSAFESHELL	"/sbin/sh"
154 
155 /* PATH= */
156 
157 #define	ZONE_DEF_PATH		"/usr/sbin:/usr/bin"
158 
159 /* error codes */
160 #define	ERR_MALLOC_FAIL		-50
161 
162 /*
163  * zone brand list structure
164  */
165 
166 struct _zoneBrandList {
167 	char			*string_ptr;
168 	struct _zoneBrandList	*next;
169 };
170 
171 /*
172  * zone status structure - used to retrieve and hold status of zones
173  */
174 
175 typedef unsigned long _zone_status_t;
176 
177 struct _zoneListElement_t {
178 	char		*_zlName;
179 	char		*_zlPath;
180 	char		*_zlScratchName;
181 	char		*_zlLockObjects;
182 	/*
183 	 * the install "state" refers to the zone states listed in
184 	 * /usr/include/libzonecfg.h that is stored in the zone_state_t
185 	 * structure and returned from getzoneent_private() - such as:
186 	 * ZONE_STATE_CONFIGURED, ZONE_STATE_INCOMPLETE,
187 	 * ZONE_STATE_INSTALLED, ZONE_STATE_READY, ZONE_STATE_MOUNTED,
188 	 * ZONE_STATE_SHUTTING_DOWN, ZONE_STATE_DOWN.
189 	 */
190 	zone_state_t	_zlOrigInstallState;
191 	zone_state_t	_zlCurrInstallState;
192 	/*
193 	 * the kernel "status" refers to the zone status listed in
194 	 * /usr/include/sys/zone.h, returned by zone_get_state(),
195 	 * and defined in the zone_status_t enum - such as:
196 	 * ZONE_IS_UNINITIALIZED, ZONE_IS_READY, ZONE_IS_BOOTING,
197 	 * ZONE_IS_RUNNING, ZONE_IS_SHUTTING_DOWN, ZONE_IS_EMPTY,
198 	 * ZONE_IS_DOWN, ZONE_IS_DYING, ZONE_IS_DEAD.
199 	 */
200 	zone_status_t	_zlOrigKernelStatus;
201 	zone_status_t	_zlCurrKernelStatus;
202 	/*
203 	 * this is an internal state recorded about the zone (ZSF_xxx).
204 	 */
205 	_zone_status_t	_zlStatus;
206 };
207 
208 typedef struct _zoneListElement_t zoneListElement_t;
209 
210 /* bits used in the _zoneListElement _zlStatus variable */
211 
212 #define	ZST_NOT_BOOTABLE	((_zone_status_t)0x00000001)
213 #define	ZST_LOCKED		((_zone_status_t)0x00000002)
214 
215 /*
216  * User-specified list of zones.
217  */
218 
219 typedef struct zone_spec_s {
220 	struct zone_spec_s	*zl_next;
221 	boolean_t		zl_used;
222 	char			zl_name[ZONENAME_MAX];
223 } zone_spec_t;
224 
225 /*
226  * The global data structure used to hold all of the global (extern) data
227  * used by this library.
228  *
229  * --> THESE DEFINITIONS ARE ORDER DEPENDENT BASED <--
230  * --> ON THE ORDER OF THE STRUCTURE INITIALIZERS! <--
231  */
232 
233 struct _z_global_data_t {
234 	char		*_z_ObjectLocks;	/* object locks held */
235 	char 		*_z_root_dir;		/* root for zone lib fctns */
236 	int		_z_SigReceived;		/* received signal count */
237 	pid_t		_z_ChildProcessId;	/* child to propagate sigs to */
238 	zone_spec_t	*_zone_spec;		/* zones to operate on */
239 	_z_printf_fcn_t	_z_echo;		/* operational message fcn */
240 	_z_printf_fcn_t	_z_echo_debug;		/* debug message fcn */
241 	_z_printf_fcn_t	_z_progerr;		/* program error fcn */
242 };
243 
244 typedef struct _z_global_data_t z_global_data_t;
245 
246 /*
247  * When _INSTZONES_LIB_Z_DEFINE_GLOBAL_DATA is defined,
248  * instzones_lib.h will define the z_global_data structure.
249  * Otherwise an extern to the structure is inserted.
250  *
251  * --> THESE DEFINITIONS ARE ORDER DEPENDENT BASED ON <--
252  * --> THE ORDER OF THE _z_global_data_t STRUCTURE!!! <--
253  */
254 
255 #if	defined(_INSTZONES_LIB_Z_DEFINE_GLOBAL_DATA)
256 
257 /* define and initialize structure */
258 
259 z_global_data_t _z_global_data = {
260 	NULL,	/* *_z_ObjectLocks */
261 	"",	/* *_z_root_dir */
262 	0,	/* _z_SigReceived */
263 	-1,	/* _z_ChildProcessId */
264 	NULL,	/* *_zone_spec */
265 	NULL,	/* _z_echo */
266 	NULL,	/* _z_echo_debug */
267 	NULL	/* _z_progerr */
268 };
269 
270 #else	/* !defined(_INSTZONES_LIB__Z_DEFINE_GLOBAL_DATA) */
271 
272 /* define structure extern */
273 
274 extern z_global_data_t _z_global_data;
275 
276 #endif	/* defined(_INSTZONES_LIB_Z_DEFINE_GLOBAL_DATA) */
277 
278 /* function prototypes */
279 
280 /*
281  *  The following functions can be used by other libs, but not
282  *  by applications.
283  */
284 
285 /* ---> zones_states.c */
286 
287 boolean_t	_z_make_zone_ready(zoneListElement_t *a_zlem);
288 boolean_t	_z_make_zone_down(zoneListElement_t *a_zlem);
289 boolean_t	_z_make_zone_running(zoneListElement_t *a_zlem);
290 int		UmountAllZones(char *mntpnt);
291 void		*_z_calloc(size_t size);
292 void		*_z_malloc(size_t size);
293 void		*_z_realloc(void *ptr, size_t size);
294 void		*_z_strdup(char *str);
295 
296 /* ---> zones_utils.c */
297 
298 /*PRINTFLIKE1*/
299 void		_z_program_error(char *fmt, ...);
300 /*PRINTFLIKE1*/
301 void		_z_echo(char *fmt, ...);
302 /*PRINTFLIKE1*/
303 void		_z_echoDebug(char *a_fmt, ...);
304 int		_z_is_directory(char *path);
305 boolean_t	_z_running_in_global_zone(void);
306 boolean_t	_z_zones_are_implemented(void);
307 void		_z_sig_trap(int a_signo);
308 int		_z_close_file_descriptors(void *a_fds, int a_fd);
309 boolean_t	_z_brands_are_implemented(void);
310 
311 
312 /* ---> zones_locks.c */
313 
314 boolean_t	_z_adjust_lock_object_for_rootpath(char **r_result,
315 			char *a_lockObject);
316 boolean_t	_z_acquire_lock(char **r_lockKey, char *a_zoneName,
317 			char *a_lock, pid_t a_pid, boolean_t a_wait);
318 boolean_t	_z_lock_zone(zoneListElement_t *a_zlst,
319 			ZLOCKS_T a_lflags);
320 boolean_t	_z_lock_zone_object(char **r_objectLocks,
321 			char *a_zoneName, char *a_lockObject,
322 			pid_t a_pid, char *a_waitingMsg,
323 			char *a_busyMsg);
324 boolean_t	_z_release_lock(char *a_zoneName, char *a_lock,
325 			char *a_key, boolean_t a_wait);
326 boolean_t	_z_unlock_zone(zoneListElement_t *a_zlst,
327 			ZLOCKS_T a_lflags);
328 boolean_t	_z_unlock_zone_object(char **r_objectLocks,
329 			char *a_zoneName, char *a_lockObject,
330 			char *a_errMsg);
331 
332 /* ---> zones_args.c */
333 
334 void		_z_free_args(argArray_t *a_args);
335 argArray_t	*_z_new_args(int initialCount);
336 /*PRINTFLIKE2*/
337 boolean_t	_z_add_arg(argArray_t *a_args, char *a_format, ...);
338 int		_z_get_argc(argArray_t *a_args);
339 char		**_z_get_argv(argArray_t *a_args);
340 
341 /* ---> zones_str.c */
342 
343 boolean_t	_z_strContainsToken(char *a_string, char *a_token,
344 			char *a_separators);
345 char		*_z_strGetToken(char *r_sep, char *a_string,
346 			int a_index, char *a_separators);
347 void		_z_strRemoveLeadingWhitespace(char **a_str);
348 void		_z_strGetToken_r(char *r_sep, char *a_string,
349 			int a_index, char *a_separators, char *a_buf,
350 			int a_bufLen);
351 void		_z_strAddToken(char **a_old, char *a_new,
352 			char a_separator);
353 void		_z_strRemoveToken(char **r_string, char *a_token,
354 			char *a_separators, int a_index);
355 /*PRINTFLIKE3*/
356 void		_z_strPrintf_r(char *a_buf, int a_bufLen,
357 			char *a_format, ...);
358 /*PRINTFLIKE1*/
359 char		*_z_strPrintf(char *a_format, ...);
360 
361 /* ---> zones_exec.c */
362 
363 int		_z_zone_exec(int *r_status, char **r_results, char *a_inputFile,
364 			char *a_path, char *a_argv[], const char *a_zoneName,
365 			int *a_fds);
366 int		_zexec(const char *a_zoneName,
367 			const char *path, char *argv[]);
368 char		*_zexec_add_env(char *name, char *value);
369 int		_zexec_init_template(void);
370 char		**_zexec_prep_env();
371 
372 /*
373  * C++ postfix
374  */
375 
376 #ifdef __cplusplus
377 }
378 #endif
379 
380 #endif	/* _INSTZONES_LIB_H */
381