1 '\" te
2 .\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved
3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH SVCPROP 1 "April 9, 2016"
7 .SH NAME
8 svcprop \- retrieve values of service configuration properties
9 .SH SYNOPSIS
10 .LP
11 .nf
12 \fBsvcprop\fR [\fB-fqtv\fR] [\fB-C\fR | \fB-c\fR | \fB-s\fR \fIsnapshot\fR]
13 [\fB-z\fR \fIzone\fR] [\fB-p\fR [\fIname\fR/]\fIname\fR]...
14 {\fIFMRI\fR | \fIpattern\fR}...
15 .fi
16
17 .LP
18 .nf
19 \fBsvcprop\fR \fB-w\fR [\fB-fqtv\fR] [\fB-z\fR \fIzone\fR] [\fB-p\fR [\fIname\fR/]\fIname\fR] {\fIFMRI\fR | \fIpattern\fR}
20 .fi
21
22 .SH DESCRIPTION
23 .LP
24 The \fBsvcprop\fR utility prints values of properties in the service
25 configuration repository. Properties are selected by \fB-p\fR options and the
26 operands.
27 .sp
28 .LP
29 Without the \fB-C\fR, \fB-c\fR, or \fB-s\fR options, \fBsvcprop\fR accesses
30 effective properties. The effective properties of a service are its directly
31 attached properties. The effective properties of a service instance are the
32 union of properties in the composed view of its \fBrunning\fR snapshot and the
33 properties in nonpersistent property groups in the composed view of the
34 instance's directly attached properties. See \fBsmf\fR(5) for an explanation of
35 property composition. If the \fBrunning\fR snapshot does not exist then the
36 instance's directly attached properties are used instead.
37 .SS "Output Format"
38 .LP
39 By default, when a single property is selected, the values for each are printed
40 on separate lines. Empty \fBASCII\fR string values are represented by a pair of
41 double quotes (\fB""\fR). Bourne shell metacharacters ('\fB;\fR', '\fB&\fR\&',
42 \&'\fB(\fR', '\fB)\fR', '\fB|\fR', '\fB^\fR', '\fB<\fR\&', '\fB>\fR', newline,
43 space, tab, backslash, '\fB"\fR', single-quote, '\fB`\fR') in \fBASCII\fR
44 string values are quoted by backslashes (\fB\e\fR).
45 .sp
46 .LP
47 When multiple properties are selected, a single line is printed for each. Each
48 line comprises a property designator, a property type, and the values (as
49 described above), separated by spaces. By default, if a single \fIFMRI\fR
50 operand has been supplied, the property designator consists of the property
51 group name and the property name joined by a slash (\fB/\fR). If multiple
52 \fIFMRI\fR operands are supplied, the designator is the canonical \fIFMRI\fR
53 for the property.
54 .sp
55 .LP
56 If access controls prohibit reading the value of a property, and no property or
57 property group is specified explicitly by a \fB-p\fR option, the property is
58 displayed as if it had no values. If one or more property or property group
59 names is specified by a \fB-p\fR option, and any property value cannot be read
60 due to access controls, an error results.
61 .sp
62 .LP
63 Error messages are printed to the standard error stream.
64 .SH OPTIONS
65 .LP
66 The following options are supported:
67 .sp
68 .ne 2
69 .na
70 \fB\fB-C\fR\fR
71 .ad
72 .RS 14n
73 Uses the directly attached properties, without composition.
74 .RE
75
76 .sp
77 .ne 2
78 .na
79 \fB\fB-c\fR\fR
80 .ad
81 .RS 14n
82 For service instances, uses the composed view of their directly attached
83 properties.
84 .RE
85
86 .sp
87 .ne 2
88 .na
89 \fB\fB-f\fR\fR
90 .ad
91 .RS 14n
92 Selects the multi-property output format, with full FMRIs as designators.
93 .RE
94
95 .sp
96 .ne 2
97 .na
98 \fB\fB-p\fR \fIname\fR\fR
99 .ad
100 .RS 14n
101 For each service or service instance specified by the operands, selects all
102 properties in the \fIname\fR property group. For property groups specified by
103 the operands, selects the \fIname\fR property.
104 .RE
105
106 .sp
107 .ne 2
108 .na
109 \fB\fB-p\fR \fIpg\fR/\fIprop\fR\fR
110 .ad
111 .RS 14n
112 Selects property \fIprop\fR in property group \fIpg\fR for each of the services
113 or service instances specified by the operands.
114 .RE
115
116 .sp
117 .ne 2
118 .na
119 \fB\fB-q\fR\fR
120 .ad
121 .RS 14n
122 Quiet. Produces no output.
123 .RE
124
125 .sp
126 .ne 2
127 .na
128 \fB\fB-s\fR \fIname\fR\fR
129 .ad
130 .RS 14n
131 Uses the composed view of the \fIname\fR snapshot for service instances.
132 .RE
133
134 .sp
135 .ne 2
136 .na
137 \fB\fB-t\fR\fR
138 .ad
139 .RS 14n
140 Selects the multi-property output format.
141 .RE
142
143 .sp
144 .ne 2
145 .na
146 \fB\fB-v\fR\fR
147 .ad
148 .RS 14n
149 Verbose. Prints error messages for nonexistent properties, even if option -q is
150 also used.
151 .RE
152
153 .sp
154 .ne 2
155 .na
156 \fB\fB-w\fR\fR
157 .ad
158 .RS 14n
159 Waits until the specified property group or the property group containing the
160 specified property changes before printing.
161 .sp
162 This option is only valid when a single entity is specified. If more than one
163 operand is specified, or an operand matches more than one instance, an error
164 message is printed and no action is taken. The -C option is implied.
165 .RE
166
167 .sp
168 .ne 2
169 .na
170 \fB-z\fR \fIzone\fR
171 .ad
172 .RS 14n
173 Uses properties from the service or instance in the specified \fIzone\fR.
174 This option is only applicable from the global zone, see \fBzones\fR(5).
175
176 .SH OPERANDS
177 .LP
178 The following operands are supported:
179 .sp
180 .ne 2
181 .na
182 \fB\fIFMRI\fR\fR
183 .ad
184 .RS 11n
185 The FMRI of a service, a service instance, a property group, or a property.
186 .sp
187 Instances and services can be abbreviated by specifying the instance name, or
188 the trailing portion of the service name. Properties and property groups must
189 be specified by a full FMRI. For example, given the FMRI:
190 .sp
191 .in +2
192 .nf
193 svc:/network/smtp:sendmail
194 .fi
195 .in -2
196 .sp
197
198 The following are valid abbreviations:
199 .sp
200 .in +2
201 .nf
202 sendmail
203 :sendmail
204 smtp
205 smtp:sendmail
206 network/smtp
207 .fi
208 .in -2
209 .sp
210
211 The following are invalid abbreviations:
212 .sp
213 .in +2
214 .nf
215 mail
216 network
217 network/smt
218 .fi
219 .in -2
220 .sp
221
222 Abbreviated forms of FMRIs are unstable and should not be used in scripts or
223 other permanent tools. If an abbreviation matches multiple instances,
224 \fBsvcprop\fR acts on each instance.
225 .RE
226
227 .sp
228 .ne 2
229 .na
230 \fBpattern\fR
231 .ad
232 .RS 11n
233 A glob pattern which is matched against the FMRIs of services and instances in
234 the repository. See \fBfnmatch\fR(5). If a pattern matches multiple services or
235 instances, \fBsvcprop\fR acts on each service or instance.
236 .RE
237
238 .SH EXAMPLES
239 .LP
240 \fBExample 1 \fRDisplaying the Value of a Single Property
241 .sp
242 .LP
243 The following example displays the value of the state property in the restarter
244 property group of instance \fBdefault\fR of service \fBsystem/cron\fR.
245
246 .sp
247 .in +2
248 .nf
249 example% svcprop -p restarter/state system/cron:default
250 online
251 .fi
252 .in -2
253 .sp
254
255 .LP
256 \fBExample 2 \fRRetrieving Whether a Service is Enabled
257 .sp
258 .LP
259 Whether a service is enabled is determined by its \fB-general/enabled\fR
260 property. This property takes immediate effect, so the \fB-c\fR option must be
261 used:
262
263 .sp
264 .in +2
265 .nf
266 example% svcprop -c -p general/enabled system/cron:default
267 true
268 .fi
269 .in -2
270 .sp
271
272 .LP
273 \fBExample 3 \fRDisplaying All Properties in a Property Group
274 .sp
275 .LP
276 On a default installation of Solaris, the following example displays all
277 properties in the \fBgeneral\fR property group of each instance of the
278 \fBnetwork/ntp\fR service:
279
280 .sp
281 .in +2
282 .nf
283 example% svcprop -p general ntp
284 general/package astring SUNWntpr
285 general/enabled boolean true
286 general/entity_stability astring Unstable
287 general/single_instance boolean true
288 .fi
289 .in -2
290 .sp
291
292 .LP
293 \fBExample 4 \fRTesting the Existence of a Property
294 .sp
295 .LP
296 The following example tests the existence of the \fBgeneral/enabled\fR property
297 for all instances of service identity:
298
299 .sp
300 .in +2
301 .nf
302 example% svcprop -q -p general/enabled identity:
303 example% echo $?
304 0
305 .fi
306 .in -2
307 .sp
308
309 .LP
310 \fBExample 5 \fRWaiting for Property Change
311 .sp
312 .LP
313 The following example waits for the \fBsendmail\fR instance to change state.
314
315 .sp
316 .in +2
317 .nf
318 example% svcprop -w -p restarter/state sendmail
319 .fi
320 .in -2
321 .sp
322
323 .LP
324 \fBExample 6 \fRRetrieving the Value of a Boolean Property in a Script
325 .sp
326 .LP
327 The following example retrieves the value of a boolean property in a script:
328
329 .sp
330 .in +2
331 .nf
332 set -- `svcprop -c -t -p general/enabled service`
333 code=$?
334 if [ $code -ne 0 ]; then
335 echo "svcprop failed with exit code $code"
336 return 1
337 fi
338 if [ $2 != boolean ]; then
339 echo "general/enabled has unexpected type $2"
340 return 2
341 fi
342 if [ $# -ne 3 ]; then
343 echo "general/enabled has wrong number of values"
344 return 3
345 fi
346 value=$3
347 \&...
348 .fi
349 .in -2
350 .sp
351
352 .LP
353 \fBExample 7 \fRUsing \fBsvcprop\fR in a Script
354 .sp
355 .in +2
356 .nf
357 example% cat getval
358 #!/bin/sh
359
360 svcprop -p $1 $2 | (
361 read value v2
362 if [ -n "$v2" ]; then echo "Multiple values!"; exit; fi
363 echo $value
364 )
365 .fi
366 .in -2
367 .sp
368
369 .SH EXIT STATUS
370 .LP
371 The following exit values are returned:
372 .sp
373 .ne 2
374 .na
375 \fB\fB0\fR\fR
376 .ad
377 .RS 5n
378 Successful completion.
379 .RE
380
381 .sp
382 .ne 2
383 .na
384 \fB\fB1\fR\fR
385 .ad
386 .RS 5n
387 An error occurred.
388 .RE
389
390 .sp
391 .ne 2
392 .na
393 \fB\fB2\fR\fR
394 .ad
395 .RS 5n
396 Invalid command line options were specified.
397 .RE
398
399 .SH SEE ALSO
400 .LP
401 \fBsvcs\fR(1), \fBinetd\fR(1M), \fBsvcadm\fR(1M), \fBsvccfg\fR(1M),
402 \fBsvc.startd\fR(1M), \fBservice_bundle\fR(4), \fBattributes\fR(5),
403 \fBfnmatch\fR(5), \fBsmf\fR(5), \fBsmf_method\fR(5), \fBsmf_security\fR(5),
404 \fBzones\fR(5)