Bug #9225

svcprop(1) could better explain behavior on services

Added by David Pacheco over 2 years ago.

Start date:
Due date:
% Done:


Estimated time:
Gerrit CR:


svcprop(1) says:

                  The FMRI of a service, a service instance, a property
                  group, or a property.

                  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.
                  Abbreviated forms of FMRIs are unstable and should not be
                  used in scripts or other permanent tools. If an
                  abbreviation matches multiple instances, svcprop acts on
                  each instance.

This is all true, but what's not obvious is that matching prefers multiple instances over a single service. For example, I have these instances in a service:

$ svcs daptest
STATE          STIME    FMRI
disabled       17:24:06 svc:/application/daptest:instance1
disabled       17:24:07 svc:/application/daptest:instance2

I can get properties for the instances as you'd expect with "svcprop daptest:instance1", as you'd expect. One might think you could get properties of the service using "svcprop daptest", but instead, you get this (I've grep'ed for only a few properties just to keep the output concise):

$ svcprop daptest | grep pgA
svc:/application/daptest:instance2/:properties/pgA/A1 astring 1
svc:/application/daptest:instance2/:properties/pgA/A2 astring 4
svc:/application/daptest:instance1/:properties/pgA/A1 astring 3
svc:/application/daptest:instance1/:properties/pgA/A2 astring 4

Those aren't the properties of the service, but rather those are the properties of all of the instances. You can get the service properties if you provide the full FMRI:

$ svcprop svc:/application/daptest | grep pgA
pgA/A1 astring 1
pgA/A2 astring 4

If you only have one instance, you still get the results from the instance, but the output looks very different from the multi-instance case because it doesn't provide the full FMRIs of the properties:

$ svccfg delete daptest:instance2
$ svcprop daptest | grep pgA
pgA/A1 astring 3
pgA/A2 astring 4
$ svcprop daptest:instance1 | grep pgA
pgA/A1 astring 3
pgA/A2 astring 4
$ svcprop svc:/application/daptest | grep pgA
pgA/A1 astring 1
pgA/A2 astring 4

(In the case that you've provided what you think is a service abbreviation like "daptest", but it matched only one instance, it's particularly unclear that the properties you're looking at are instance properties, not service properties.)

I think it would help a lot to explain that if a service has any instances, then a partial FMRI that matches the service will instead match all of the instances. In fact, unless there are 0 instances, I think the only way to get the values for the service itself are to provide the full FMRI.

Relatedly, the manual page says:

       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 FMRI operand has been supplied, the property designator
       consists of the property group name and the property name joined by a
       slash (/). If multiple FMRI operands are supplied, the designator is
       the canonical FMRI for the property.

I think the output above shows that's not quite true -- it's not whether multiple FMRI operands are supplied that determines whether the canonical FMRI is used, but rather whether multiple FMRIs were matched by any number of operands.

Also relatedly, it might be worth mentioning that the "-c" and "-C" flags appear to have no effect on services. For "-c", it's totally unspecified what the flag means for services. Since it normally seems to change the behavior from looking at the running snapshot to looking at the directly attached properties (see #9224), it makes sense that it would be a no-op for services, for which the default behavior is already to look only at directly attached properties. It also makes sense that "-C' would be a no-op because it's specified to ignore composition, and composition doesn't have any effect for services. (Much of this can be worked out by process of elimination, but when you're still trying to figure out what "directly-attached" and "composition" refer to, it's somewhat confusing that the docs don't mention that these flags only make sense for instances.)

Also available in: Atom PDF