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