share/man/man1/svcprop.1

   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(8), \fBsvcadm\fR(8), \fBsvccfg\fR(8),
 402 \fBsvc.startd\fR(8), \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)