xref: /titanic_51/usr/src/lib/libscf/inc/libscf_priv.h (revision 7b209c2cc5ea45251aba06dcc6181d3f23da807a)
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 #ifndef	_LIBSCF_PRIV_H
27 #define	_LIBSCF_PRIV_H
28 
29 #pragma ident	"%Z%%M%	%I%	%E% SMI"
30 
31 #include <libscf.h>
32 #include <unistd.h>
33 
34 #ifdef	__cplusplus
35 extern "C" {
36 #endif
37 
38 /*
39  * NOTE
40  *
41  * The contents of this file are private to the implementation of Solaris
42  * and are subject to change at any time without notice.
43  */
44 
45 #define	SCF_PG_GENERAL_TYPE		SCF_GROUP_FRAMEWORK
46 #define	SCF_PG_GENERAL_FLAGS		0
47 
48 #define	SCF_PG_GENERAL_OVR_TYPE		SCF_GROUP_FRAMEWORK
49 #define	SCF_PG_GENERAL_OVR_FLAGS	SCF_PG_FLAG_NONPERSISTENT
50 
51 #define	SCF_PG_OPTIONS_TYPE		SCF_GROUP_FRAMEWORK
52 #define	SCF_PG_OPTIONS_FLAGS		0
53 
54 #define	SCF_PG_OPTIONS_OVR_TYPE		SCF_GROUP_FRAMEWORK
55 #define	SCF_PG_OPTIONS_OVR_FLAGS	SCF_PG_FLAG_NONPERSISTENT
56 
57 #define	SCF_PG_RESTARTER_TYPE		SCF_GROUP_FRAMEWORK
58 #define	SCF_PG_RESTARTER_FLAGS		SCF_PG_FLAG_NONPERSISTENT
59 
60 #define	SCF_PG_RESTARTER_ACTIONS_TYPE	SCF_GROUP_FRAMEWORK
61 #define	SCF_PG_RESTARTER_ACTIONS_FLAGS	SCF_PG_FLAG_NONPERSISTENT
62 
63 #define	SCF_PROPERTY_CLEAR		((const char *)"maint_off")
64 #define	SCF_PROPERTY_MAINTENANCE	((const char *)"maint_on")
65 
66 #define	SCF_PROPERTY_LOGFILE		((const char *)"logfile")
67 #define	SCF_PROPERTY_ALT_LOGFILE	((const char *)"alt_logfile")
68 
69 #define	SCF_LEGACY_SERVICE		((const char *)"smf/legacy_run")
70 
71 #define	SCF_LEGACY_PROPERTY_NAME	((const char *)"name")
72 #define	SCF_LEGACY_PROPERTY_INODE	((const char *)"inode")
73 #define	SCF_LEGACY_PROPERTY_SUFFIX	((const char *)"suffix")
74 
75 #define	SCF_FMRI_TYPE_SVC		0x1
76 #define	SCF_FMRI_TYPE_FILE		0x2
77 
78 /*
79  * Strings for use in constructing FMRIs
80  */
81 #define	SCF_FMRI_SVC_PREFIX		"svc:"
82 #define	SCF_FMRI_FILE_PREFIX		"file:"
83 #define	SCF_FMRI_SCOPE_PREFIX		"//"
84 #define	SCF_FMRI_LOCAL_SCOPE		"localhost"
85 #define	SCF_FMRI_SCOPE_SUFFIX		"@localhost"
86 #define	SCF_FMRI_SERVICE_PREFIX		"/"
87 #define	SCF_FMRI_INSTANCE_PREFIX	":"
88 #define	SCF_FMRI_PROPERTYGRP_PREFIX	"/:properties/"
89 #define	SCF_FMRI_PROPERTY_PREFIX	"/"
90 #define	SCF_FMRI_LEGACY_PREFIX		"lrc:"
91 
92 /*
93  * sulogin Service FMRI
94  */
95 #define	SVC_SULOGIN_FMRI ((const char *)"svc:/system/sulogin")
96 
97 typedef struct scf_decoration_info {
98 	const char *sdi_name;
99 	scf_type_t sdi_type;
100 	scf_value_t *sdi_value;		/* can be SCF_DECORATE_CLEAR */
101 } scf_decoration_info_t;
102 
103 typedef int (*scf_decoration_func)(const scf_decoration_info_t *, void *);
104 
105 /*
106  * calls a callback function for each decoration on the handle.  If the
107  * callback returns 0, the iteration stops and returns 0.  If the callback
108  * returns a non-zero value, the iteration continues.  After full completion,
109  * 1 is returned.  On error, -1 is returned.
110  */
111 int _scf_handle_decorations(scf_handle_t *, scf_decoration_func *,
112     scf_value_t *, void *);
113 
114 /*
115  * wait for a change to the propertygroup -- may return early.
116  * For now, only one of these can be outstanding at a time.
117  *
118  * The second argument is how long, in seconds, to wait for a response.
119  *
120  * Returns SCF_COMPLETE on timeout, -1 on error, and SCF_SUCCESS in every
121  * other case.  You must call scf_pg_update() to see if the object has
122  * actually changed.
123  */
124 int _scf_pg_wait(scf_propertygroup_t *, int);
125 
126 /*
127  * set up notifications for changes to a class of property groups (by name
128  * and type)
129  *
130  * Only one thread can be sleeping in _scf_notify_wait() -- others will
131  * fail.  Deletions give an fmri in the output path.
132  *
133  * These do not survive unbind()->bind() -- in fact, that is currently the
134  * only way to clear them.
135  */
136 int _scf_notify_add_pgname(scf_handle_t *, const char *);
137 int _scf_notify_add_pgtype(scf_handle_t *, const char *);
138 int _scf_notify_wait(scf_propertygroup_t *, char *, size_t);
139 
140 /*
141  * Internal interfaces for snapshot creation:
142  *	_scf_snapshot_take_new(), _scf_snapshot_take_new_named(), and
143  *	_scf_snapshot_take_attach() create a set of snaplevels
144  *	containing frozen versions of both the instance's property groups and
145  *	its parent service's property groups. _scf_snapshot_take_new() and
146  *	_scf_snapshot_take_new_named() create a new snapshot to which the
147  *	new snaplevels are attached, while _scf_snapshot_take_attach()
148  *	attaches the new snaplevels to a pre-existing snapshot.
149  *
150  *	_scf_snapshot_take_new_named() records the passed in names into the
151  *	snaplevel instead of the instance and service name.  This creates
152  *	an inconsistency, which should be resolved by using
153  *	_scf_snapshot_attach() to attach the new snaplevels to a snapshot
154  *	underneath the appropriate instance.  The first snapshot can
155  *	then be deleted.
156  *
157  *	_scf_snapshot_attach(snap1, snap2) points snap2 at the snaplevels
158  *	pointed to by snap1.  After a call to either
159  *	_scf_snapshot_take_attach(snap1, snap2) or
160  *	_scf_snapshot_attach(inst, snap), scf_snapshot_update() will be
161  *	required for any open references to snap or snap2 to see the new
162  *	snaplevels.
163  *
164  *	_scf_snapshot_delete() deletes the snapshot object.  While
165  *	snaplevels, being only loosely connected to snapshots, stay
166  *	around until they are no longer referenced, any references *through
167  *	this snapshot object* will be invalidated.
168  *
169  * _scf_snapshot_take_new() can fail with at least _HANDLE_MISMATCH,
170  * _CONNECTION_BROKEN, _INVALID_ARGUMENT, _NO_RESOURCES, _PERMISSION_DENIED,
171  * _NOT_SET, _EXISTS.
172  *
173  * _scf_snapshot_take_new_named() can fail with at least _HANDLE_MISMATCH,
174  * _CONNECTION_BROKEN, _INVALID_ARGUMENT, _NO_RESOURCES, _PERMISSION_DENIED,
175  * _NOT_SET, _EXISTS.
176  *
177  * _scf_snapshot_take_attach() can fail with _CONNECTION_BROKEN, _NOT_SET,
178  * _PERMISSION_DENIED, _NO_RESOURCES, _INVALID_ARGUMENT.
179  *
180  * _scf_snapshot_attach() can fail with _HANDLE_MISMATCH, _CONNECTION_BROKEN,
181  * _NOT_SET, _NO_RESOURCES, _PERMISSION_DENIED.
182  */
183 int _scf_snapshot_take_new(scf_instance_t *, const char *, scf_snapshot_t *);
184 int _scf_snapshot_take_new_named(scf_instance_t *,
185     const char *, const char *, const char *, scf_snapshot_t *);
186 int _scf_snapshot_take_attach(scf_instance_t *, scf_snapshot_t *);
187 int _scf_snapshot_attach(scf_snapshot_t *, scf_snapshot_t *);
188 int _scf_snapshot_delete(scf_snapshot_t *);
189 
190 /*
191  * Destructively portions up the first argument into the different portions
192  * of a svc: fmri, and returns pointers to the applicable portions.  Omitted
193  * portions are set to NULL, except for the scope, which is set to the
194  * default local scope if not specified.
195  *
196  * Parsing is attempted in the order of: svc:, file:. The identified type
197  * of the service is returned in the second argument and may take a value
198  * of: SCF_FMRI_TYPE_SVC or SCF_FMRI_TYPE_FILE.
199  *
200  * Note that some of the returned pointers (in particular the scope) may not
201  * point into the passed buffer.
202  */
203 int scf_parse_fmri(char *, int *, const char **, const char **, const char **,
204     const char **, const char **);
205 
206 int scf_parse_svc_fmri(char *, const char **, const char **, const char **,
207     const char **, const char **);
208 
209 int scf_parse_file_fmri(char *fmri, const char **scope, const char **path);
210 
211 ssize_t scf_canonify_fmri(const char *, char *, size_t);
212 
213 const char *scf_type_to_string(scf_type_t);
214 scf_type_t scf_string_to_type(const char *);
215 
216 int _smf_refresh_instance_i(scf_instance_t *);
217 
218 typedef struct scf_simple_handle {
219 	scf_handle_t		*h;
220 	scf_snapshot_t		*snap;
221 	scf_instance_t		*inst;
222 	scf_propertygroup_t	*running_pg;
223 	scf_propertygroup_t	*editing_pg;
224 } scf_simple_handle_t;
225 
226 void scf_simple_handle_destroy(scf_simple_handle_t *);
227 scf_simple_handle_t *scf_general_pg_setup(const char *, const char *);
228 scf_transaction_t *scf_transaction_setup(scf_simple_handle_t *);
229 int scf_transaction_restart(scf_simple_handle_t *, scf_transaction_t *);
230 int scf_read_count_property(scf_simple_handle_t *, char *, uint64_t *);
231 int scf_set_count_property(scf_transaction_t *, char *, uint64_t, boolean_t);
232 
233 /*
234  * Walks all the instances matching a given fmri list.  Each fmri in the array
235  * can be one of the following:
236  *
237  * 	- Full instance name
238  * 	- Full service name
239  * 	- Full property group or property name
240  * 	- Partial service or instance name
241  * 	- A globbed pattern
242  *
243  * The matching rules for partial fmris are a slightly more complex.  We allow
244  * for any substring anchored at the end of the instance or service name,
245  * provided it begins with a complete element in the fmri.  For example, given
246  * the fmri "svc:/system/filesystem/local:default", any of the following would
247  * be acceptable matches: 'default', 'local', 'local:default',
248  * 'filesystem/local'.  The following would not be acceptable:
249  * 'system/filesystem', 'filesystem/loc', 'system/local'.  Possible flag values:
250  *
251  * 	SCF_WALK_MULTIPLE	Allow individual arguments to correspond to
252  * 				multiple instances.
253  *
254  * 	SCF_WALK_LEGACY		Walk legacy services (indicated by a non-NULL
255  * 				propery group).
256  *
257  * 	SCF_WALK_SERVICE	If the user specifies a service, pass the
258  * 				service to the callback without iterating over
259  * 				its instances.
260  *
261  * 	SCF_WALK_PROPERTY	Allow FMRIs which match property groups or
262  * 				individual properties.  Incompatible with
263  * 				SCF_WALK_LEGACY.
264  *
265  * 	SCF_WALK_NOINSTANCE	Walk only services.  Must be used in
266  * 				conjunction with SCF_WALK_SERVICE.
267  *
268  * 	SCF_WALK_EXPLICIT	Walk only services if the match is exact
269  *				else return instances. Must be used in
270  *				conjunction with SCF_WALK_SERVICE.
271  *
272  * If no arguments are given, then all instances in the service graph are
273  * walked.
274  *
275  * The second to last parameter is set to UU_EXIT_FATAL if one of the arguments
276  * is an invalid FMRI or matches multiple FMRIs when SCF_WALK_MULTIPLE is not
277  * set.
278  *
279  * The last parameter is a user-supplied error function that is called when
280  * reporting invalid arguments.
281  */
282 
283 #define	SCF_WALK_MULTIPLE	0x01
284 #define	SCF_WALK_LEGACY		0x02
285 #define	SCF_WALK_SERVICE	0x04
286 #define	SCF_WALK_PROPERTY	0x08
287 #define	SCF_WALK_NOINSTANCE	0x10
288 #define	SCF_WALK_EXPLICIT	0x20
289 
290 /*
291  * The default locations of the repository dbs
292  */
293 #define	REPOSITORY_DB		"/etc/svc/repository.db"
294 #define	NONPERSIST_DB		"/etc/svc/volatile/svc_nonpersist.db"
295 #define	FAST_REPOSITORY_DB	"/etc/svc/volatile/fast_repository.db"
296 
297 
298 typedef struct scf_walkinfo {
299 	const char		*fmri;
300 	scf_scope_t		*scope;
301 	scf_service_t		*svc;
302 	scf_instance_t		*inst;
303 	scf_propertygroup_t	*pg;
304 	scf_property_t		*prop;
305 	int			count;	/* svcprop special */
306 } scf_walkinfo_t;
307 
308 typedef int (*scf_walk_callback)(void *, scf_walkinfo_t *);
309 
310 scf_error_t scf_walk_fmri(scf_handle_t *, int, char **, int,
311     scf_walk_callback, void *, int *, void (*)(const char *, ...));
312 
313 /*
314  * Requests a backup of the repository with a particular name, which
315  * can be any alphabetic string.  Only privileged users can do this.
316  *
317  * Can fail with:
318  *	_NOT_BOUND, _CONNECTION_BROKEN, _PERMISSION_DENIED, _INVALID_ARGUMENT,
319  *	_INTERNAL (path too long, or the backup failed for an odd reason),
320  *	_BACKEND_READONLY (filesystem is still read-only)
321  */
322 int _scf_request_backup(scf_handle_t *, const char *);
323 
324 /*
325  * Repository switch client
326  */
327 int _scf_repository_switch(scf_handle_t *, int);
328 
329 /*
330  * Determines whether a property group requires authorization to read; this
331  * does not in any way reflect whether the caller has that authorization.
332  * To determine that, the caller must attempt to read the value of one of the
333  * group's properties.
334  *
335  * Can fail with:
336  *	_NOT_BOUND, _CONNECTION_BROKEN, _INVALID_ARGUMENT, _INTERNAL,
337  *	_NO_RESOURCES, _CONSTRAINT_VIOLATED, _DELETED.
338  */
339 int _scf_pg_is_read_protected(const scf_propertygroup_t *, boolean_t *);
340 
341 /*
342  * Sets annotation data for SMF audit logging.  Once this function has been
343  * set, the next audit record will be preceded by an ADT_smf_annotation
344  * with the information provided in this function.  This function is used
345  * to mark operations which comprise multiple primitive operations such as
346  * svccfg import.
347  */
348 int _scf_set_annotation(scf_handle_t *h, const char *operation,
349     const char *file);
350 
351 /*
352  * scf_pattern_t
353  */
354 typedef struct scf_pattern {
355 	enum	{
356 		PATTERN_INVALID,	/* Uninitialized state */
357 		PATTERN_EXACT,
358 		PATTERN_GLOB,
359 		PATTERN_PARTIAL
360 	} sp_type;
361 	char			*sp_arg;	/* Original argument */
362 	struct scf_match	*sp_matches;	/* List of matches */
363 	int			sp_matchcount;	/* # of matches */
364 } scf_pattern_t;
365 
366 int scf_cmp_pattern(char *, scf_pattern_t *);
367 
368 int gen_filenms_from_fmri(const char *, const char *, char *, char *);
369 
370 #ifdef	__cplusplus
371 }
372 #endif
373 
374 #endif	/* _LIBSCF_PRIV_H */
375