path: root/usr/src/man/man1/svcprop.1

'\" te
.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved
.\" Copyright 2019 Joyent, Inc.
.\" 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.
.\" 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.
.\" 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]
.TH SVCPROP 1 "Dec 11, 2019"
.SH NAME
svcprop \- retrieve values of service configuration properties
.SH SYNOPSIS
.nf
\fBsvcprop\fR [\fB-fqtv\fR] [\fB-C\fR | \fB-c\fR | \fB-s\fR \fIsnapshot\fR]
     [\fB-z\fR \fIzone\fR] [\fB-p\fR [\fIname\fR/]\fIname\fR]...
     {\fIFMRI\fR | \fIpattern\fR}...
.fi

.LP
.nf
\fBsvcprop\fR \fB-w\fR [\fB-fqtv\fR] [\fB-z\fR \fIzone\fR] [\fB-p\fR [\fIname\fR/]\fIname\fR] {\fIFMRI\fR | \fIpattern\fR}
.fi

.SH DESCRIPTION
The \fBsvcprop\fR utility prints values of properties in the service
configuration repository. Properties are selected by \fB-p\fR options and the
operands.
.sp
.LP
Without the \fB-C\fR, \fB-c\fR, or \fB-s\fR options, \fBsvcprop\fR accesses
effective properties. The effective properties of a service are its directly
attached properties. The effective properties of a service instance are the
union of properties in the composed view of its \fBrunning\fR snapshot and the
properties in nonpersistent property groups in the composed view of the
instance's directly attached properties. See \fBsmf\fR(7) for an explanation of
property composition. If the \fBrunning\fR snapshot does not exist then the
instance's directly attached properties are used instead.
.SS "Output Format"
By default, when a single property is selected, the values for each are printed
on separate lines. Empty \fBASCII\fR string values are represented by a pair of
double quotes (\fB""\fR). Bourne shell metacharacters ('\fB;\fR', '\fB&\fR\&',
\&'\fB(\fR', '\fB)\fR', '\fB|\fR', '\fB^\fR', '\fB<\fR\&', '\fB>\fR', newline,
space, tab, backslash, '\fB"\fR', single-quote, '\fB`\fR') in \fBASCII\fR
string values are quoted by backslashes (\fB\e\fR).
.sp
.LP
When multiple properties are selected, a single line is printed for each. Each
line comprises a property designator, a property type, and the values (as
described above), separated by spaces. By default, if a single \fIFMRI\fR
operand has been supplied, the property designator consists of the property
group name and the property name joined by a slash (\fB/\fR). If multiple
\fIFMRI\fR operands are supplied, the designator is the canonical \fIFMRI\fR
for the property.
.sp
.LP
If access controls prohibit reading the value of a property, and no property or
property group is specified explicitly by a \fB-p\fR option, the property is
displayed as if it had no values. If one or more property or property group
names is specified by  a \fB-p\fR option, and any property value cannot be read
due to access controls, an error results.
.sp
.LP
Error messages are printed to the standard error stream.
.SH OPTIONS
The following options are supported:
.sp
.ne 2
.na
\fB\fB-C\fR\fR
.ad
.RS 14n
Uses the directly attached properties, without composition.
.RE

.sp
.ne 2
.na
\fB\fB-c\fR\fR
.ad
.RS 14n
For service instances, uses the composed view of their directly attached
properties.
.RE

.sp
.ne 2
.na
\fB\fB-f\fR\fR
.ad
.RS 14n
Selects the multi-property output format, with full FMRIs as designators.
.RE

.sp
.ne 2
.na
\fB\fB-p\fR \fIname\fR\fR
.ad
.RS 14n
For each service or service instance specified by the operands, selects all
properties in the \fIname\fR property group. For property groups specified by
the operands, selects the \fIname\fR property.
.RE

.sp
.ne 2
.na
\fB\fB-p\fR \fIpg\fR/\fIprop\fR\fR
.ad
.RS 14n
Selects property \fIprop\fR in property group \fIpg\fR for each of the services
or service instances specified by the operands.
.RE

.sp
.ne 2
.na
\fB\fB-q\fR\fR
.ad
.RS 14n
Quiet. Produces no output.
.RE

.sp
.ne 2
.na
\fB\fB-s\fR \fIname\fR\fR
.ad
.RS 14n
Uses the composed view of the \fIname\fR snapshot for service instances.
.RE

.sp
.ne 2
.na
\fB\fB-t\fR\fR
.ad
.RS 14n
Selects the multi-property output format.
.RE

.sp
.ne 2
.na
\fB\fB-v\fR\fR
.ad
.RS 14n
Verbose. Prints error messages for nonexistent properties, even if option -q is
also used.
.RE

.sp
.ne 2
.na
\fB\fB-w\fR\fR
.ad
.RS 14n
Waits until the specified property group or the property group containing the
specified property changes before printing.
.sp
This option is only valid when a single entity is specified. If more than one
operand is specified, or an operand matches more than one instance, an error
message is printed and no action is taken. The -C option is implied.
.RE

.sp
.ne 2
.na
\fB-z\fR \fIzone\fR
.ad
.RS 14n
Uses properties from the service or instance in the specified \fIzone\fR.
This option is only applicable from the global zone, see \fBzones\fR(7).

.SH OPERANDS
The following operands are supported:
.sp
.ne 2
.na
\fB\fIFMRI\fR\fR
.ad
.RS 11n
The FMRI of a service, a service instance, a property group, or a property.
.sp
Instances and services can be abbreviated by specifying the instance name, or
the trailing portion of the service name. Properties and property groups must
be specified by a full FMRI. For example, given the FMRI:
.sp
.in +2
.nf
svc:/network/smtp:sendmail
.fi
.in -2
.sp

The following are valid abbreviations:
.sp
.in +2
.nf
sendmail
:sendmail
smtp
smtp:sendmail
network/smtp
.fi
.in -2
.sp

The following are invalid abbreviations:
.sp
.in +2
.nf
mail
network
network/smt
.fi
.in -2
.sp

Abbreviated forms of FMRIs are unstable and should not be used in scripts or
other permanent tools. If an abbreviation matches multiple instances,
\fBsvcprop\fR acts on each instance.
.RE

.sp
.ne 2
.na
\fBpattern\fR
.ad
.RS 11n
A glob pattern which is matched against the FMRIs of services and instances in
the repository. See \fBfnmatch\fR(7). If a pattern matches multiple services or
instances, \fBsvcprop\fR acts on each service or instance.
.RE

.SH EXAMPLES
\fBExample 1 \fRDisplaying the Value of a Single Property
.sp
.LP
The following example displays the value of the state property in the restarter
property group of instance \fBdefault\fR of service \fBsystem/cron\fR.

.sp
.in +2
.nf
example%  svcprop -p restarter/state system/cron:default
online
.fi
.in -2
.sp

.LP
\fBExample 2 \fRRetrieving Whether a Service is Enabled
.sp
.LP
Whether a service is enabled is determined by its \fB-general/enabled\fR
property. This property takes immediate effect, so the \fB-c\fR option must be
used:

.sp
.in +2
.nf
example%  svcprop -c -p general/enabled system/cron:default
true
.fi
.in -2
.sp

.LP
\fBExample 3 \fRDisplaying All Properties in a Property Group
.sp
.LP
On a default installation of Solaris, the following example displays all
properties in the \fBgeneral\fR property group of each instance of the
\fBnetwork/ntp\fR service:

.sp
.in +2
.nf
example% svcprop -p general ntp
general/package astring SUNWntpr
general/enabled boolean true
general/entity_stability astring Unstable
.fi
.in -2
.sp

.LP
\fBExample 4 \fRTesting the Existence of a Property
.sp
.LP
The following example tests the existence of the \fBgeneral/enabled\fR property
for all instances of service identity:

.sp
.in +2
.nf
example%  svcprop -q -p general/enabled identity:
example%  echo $?
0
.fi
.in -2
.sp

.LP
\fBExample 5 \fRWaiting for Property Change
.sp
.LP
The following example waits for the \fBsendmail\fR instance to change state.

.sp
.in +2
.nf
example%  svcprop -w -p restarter/state sendmail
.fi
.in -2
.sp

.LP
\fBExample 6 \fRRetrieving the Value of a Boolean Property in a Script
.sp
.LP
The following example retrieves the value of a boolean property in a script:

.sp
.in +2
.nf
set -- `svcprop -c -t -p general/enabled service`
code=$?
if [ $code -ne 0 ]; then
        echo "svcprop failed with exit code $code"
        return 1
fi
if [ $2 != boolean ]; then
         echo "general/enabled has unexpected type $2"
         return 2
fi
if [ $# -ne 3 ]; then
          echo "general/enabled has wrong number of values"
          return 3
fi
value=$3
\&...
.fi
.in -2
.sp

.LP
\fBExample 7 \fRUsing \fBsvcprop\fR in a Script
.sp
.in +2
.nf
example% cat getval
#!/bin/sh

svcprop -p $1 $2 | (
         read value v2
         if [ -n "$v2" ]; then echo "Multiple values!"; exit; fi
         echo $value
       )
.fi
.in -2
.sp

.SH EXIT STATUS
The following exit values are returned:
.sp
.ne 2
.na
\fB\fB0\fR\fR
.ad
.RS 5n
Successful completion.
.RE

.sp
.ne 2
.na
\fB\fB1\fR\fR
.ad
.RS 5n
An error occurred.
.RE

.sp
.ne 2
.na
\fB\fB2\fR\fR
.ad
.RS 5n
Invalid command line options were specified.
.RE

.SH SEE ALSO
.BR svcs (1),
.BR service_bundle (5),
.BR attributes (7),
.BR fnmatch (7),
.BR smf (7),
.BR smf_method (7),
.BR smf_security (7),
.BR zones (7),
.BR inetd (8),
.BR svc.startd (8),
.BR svcadm (8),
.BR svccfg (8)