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