Bug #9225
opensvcprop(1) could better explain behavior on services
0%
Description
svcprop(1) says:
FMRI 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.)
No data to display